NAME

       cargo-auditable  - Embed a JSON formatted dependency tree into a dedicated linker section of the compiled
       executable

SYNOPSIS

       cargo-auditable

DESCRIPTION

       Know the exact crate versions used to build your Rust  executable.  Audit  binaries  for  known  bugs  or
       security vulnerabilities in production, at scale, with zero bookkeeping.

       This  works by embedding data about the dependency tree in JSON format into a dedicated linker section of
       the compiled executable.

       Linux, Windows and Mac OS are officially supported. All other ELF targets should work, but are not tested
       on CI. WASM is currently not supported, but patches are welcome.

       The end goal is to get Cargo itself to encode this information in  binaries.  There  is  an  RFC  for  an
       implementation      within      Cargo,      for     which     this     project     paves     the     way:
       https://github.com/rust-lang/rfcs/pull/2801

USAGE

       cargo auditable works with any Cargo command. All arguments are passed to cargo as-is.

FAQ

       Doesn't this bloat my binary?

       In a word, no. The embedded dependency list uses under 4kB even  on  large  dependency  trees  with  400+
       entries. This typically translates to between 1/1000 and 1/10,000 of the size of the binary.

       Can I make cargo always build with cargo auditable?

       Yes! For example, on Linux/macOS/etc add this to your .bashrc:

       alias cargo="cargo auditable"

       If   you're   using   a   shell   other  than  bash,  or  if  using  an  alias  is  not  an  option,  see
       https://github.com/rust-secure-code/cargo-auditable/blob/HEAD/REPLACING_CARGO.md.

       Is there any tooling to consume this data?

       Vulnerability reporting

           cargo audit v0.17.3+ can detect this data in binaries and report on  vulnerabilities.  See  here  for
       details.
           trivy  v0.31.0+ detects this data in binaries and reports on vulnerabilities. See the v0.31.0 release
       notes for an end-to-end example.

       Recovering the dependency list

           syft v0.53.0+ has experimental support for detecting this data in binaries. When used  on  images  or
       directories,  Rust  audit  support  must  be  enabled by adding the --catalogers all CLI option, e.g syft
       --catalogers all <container image containing Rust auditable binary>.
           rust-audit-info recovers the dependency list from a binary and prints it in JSON.

       It is also interoperable with existing tooling that consumes Cargo.lock via the  JSON-to-TOML  convertor.
       However,  we  recommend  supporting the format natively; the format is designed to be very easy to parse,
       even if your language does not have a library for that yet.

       Can I read this data using a tool written in a different language?

       Yes. The data format is designed for interoperability with alternative implementations. In fact,  parsing
       it           only           takes           5           lines           of           Python.          See
       https://github.com/rust-secure-code/cargo-auditable/blob/HEAD/PARSING.md for documentation on parsing the
       data.

       What is the data format, exactly?

       The        data        format        is        described        by        the         JSON         schema
       https://github.com/rust-secure-code/cargo-auditable/blob/HEAD/cargo-auditable.schema.json.  The  JSON  is
       Zlib-compressed and placed in a linker section named .dep-v0. You can find more  info  about  parsing  it
       here.

       What about embedded platforms?

       Embedded  platforms where you cannot spare a byte should not add anything in the executable. Instead they
       should record the hash of every executable in a database and associate  the  hash  with  its  Cargo.lock,
       compiler  and  LLVM  version,  build date, etc. This would make for an excellent Cargo wrapper or plugin.
       Since that can be done in a 5-line shell script, writing that tool is left as an exercise to the reader.

       Does this impact reproducible builds?

       The data format is specifically designed not to disrupt reproducible builds. It contains  no  timestamps,
       and  the  generated  JSON  is sorted to make sure it is identical between compilations. If anything, this
       helps with reproducible builds, since you know all the versions for a given binary now.

       Does this disclose any sensitive information?

       No. All URLs and file paths are redacted, but the crate names and versions are recorded as-is. At present
       panic messages already disclose all this info and more. Also, chances are that you're  legally  obligated
       have to disclose use of specific open-source crates anyway, since MIT and many other licenses require it.

       What about recording the compiler version?

       The compiler itself will start embedding it soon.

       On  older  versions  it's  already there in the debug info. On Unix you can run strings your_executable |
       grep 'rustc version' to see it.

       What about keeping track of versions of statically linked C libraries?

       Good question. I don't think they are exposed in any reasonable way right now. Would be a great addition,
       but not required for the initial launch. We can add it later in a backwards-compatible way. Adopting  the
       -src  crate  convention  would  make it happen naturally, and will have other benefits as well, so that's
       probably the best route.

       What is blocking uplifting this into Cargo?

       Cargo itself is currently in a feature freeze.

EXIT STATUS

       0      Successful program execution.

       1      Unsuccessful program execution.

       101    The program panicked.

EXAMPLES

       Build your project with dependency lists embedded in the binaries
              # cargo auditable build --release

AUTHOR

         Sergey "Shnatsel" Davidoff <shnatsel@gmail.com>

                                                                                              CARGO-AUDITABLE(1)