|
5 | 5 | [](https://badge.fury.io/py/it-depends) |
6 | 6 | [](https://slack.empirehacking.nyc) |
7 | 7 |
|
8 | | -It-Depends is a tool to automatically build a dependency graph and Software Bill of Materials (SBOM) for packages and arbitrary source code repositories. You can use it to enumerate all third party dependencies for a software package, map those dependencies to known security vulnerabilities, as well as compare the similarity between two packages based on their dependencies. |
| 8 | +It-Depends is a tool to automatically build a dependency graph and Software Bill of Materials (SBOM) for packages and arbitrary source code repositories. It supports Go, JavaScript, Rust, Python, C/C++ (cmake and autotools), and Ubuntu packages. |
9 | 9 |
|
10 | | -To the best of our knowledge, It-Depends is the only such tool with the following features: |
| 10 | +What makes it different from [similar tools](SIMILAR.md): |
11 | 11 |
|
12 | | -* Support for C/C++ projects (both autootools and cmake) |
13 | | -* Automated resolution of native library dependencies partially based on dynamic analysis (_e.g._, the Python package `pytz` depends on the native library `libtinfo.so.6`) |
14 | | -* Enumeration of _all possible_ dependency resolutions, not just a _single feasible_ resolution |
15 | | -* A comparison metric for the similarity between two packages based on their dependency graph |
| 12 | +* Resolves _all possible_ dependency versions, not just a single feasible resolution |
| 13 | +* C/C++ support via cmake and autotools without building the project |
| 14 | +* Automated native library dependency mapping via dynamic analysis (_e.g._, `pytz` depends on `libtinfo.so.6`) |
| 15 | +* Vulnerability scanning against the [OSV database](https://osv.dev/) |
| 16 | +* Dependency similarity comparison between packages |
16 | 17 |
|
17 | | -## Features |
18 | | - |
19 | | -* Supports Go, JavaScript, Rust, Python, and C/C++ projects. |
20 | | -* Accepts source code repositories or package specifications like `pip:it-depends` |
21 | | -* Extracts dependencies of cmake/autotool repostories without building it |
22 | | -* Finds native dependencies for high level languages like Python or JavaScript |
23 | | -* Provides visualization based on vis.js or dot |
24 | | -* Matches dependencies and CVEs |
25 | | -* Export Software Bills of Materials (SBOMs) |
26 | | - * Machine-intelligible JSON output |
27 | | - * Support for the SPDX standard is [in active development](https://github.com/trailofbits/it-depends/tree/dev/spdx) |
28 | | - |
29 | | -### Can It-Depends Do It? It Depends. |
30 | | - |
31 | | -* It-Depends does not detect vendored or copy/pasted dependencies |
32 | | -* Results from build systems like autotools and cmake that entail arbitrary computation at install time are |
33 | | - best-effort |
34 | | -* Resolution of native dependencies is best-effort |
35 | | - * Some native dependencies are resolved through dynamic analysis |
36 | | - * Native dependencies are inferred by cross-referencing file requirements against paths provided by the Ubuntu |
37 | | - package repository; dependencies may be different across other Linux distributions or Ubuntu versions |
38 | | -* It-Depends attempts to resolve _all_ possible package versions that satisfy a dependency |
39 | | - * It-Depends _does not_ find a single satisfying package resolution |
40 | | - * The list of resolved packages is intended to be a superset of the packages required by the installation of |
41 | | - a package on any system |
42 | | - * The `--audit` feature may discover vulnerabilities in upstream dependencies that are either not exploitable in the |
43 | | - target package or are in a package version that cannot exist in any valid dependency resolution of the target |
44 | | - package |
45 | | -* It-Depends caches data that it expects to be immutable in a local database |
46 | | - * If a package is ever deleted or yanked from a package repository after it was already cached, It-Depends will |
47 | | - continue to use the cached data unless the cache is cleared with `--clear-cache` |
48 | | - |
49 | | -## Quickstart |
| 18 | +## Installation |
50 | 19 |
|
51 | 20 | ```shell |
52 | 21 | pip3 install it-depends |
53 | | -python -c "import it_depends as it; print(it.__version__)" |
54 | | -``` |
55 | | - |
56 | | -### Running it |
57 | | - |
58 | | -Run `it-depends` in the root of the source repository you would like to analyze: |
59 | | - |
60 | | -```shell |
61 | | -cd /path/to/project |
62 | | -it-depends . |
63 | | -``` |
64 | | - |
65 | | -or alternatively point it to the path directly: |
66 | | - |
67 | | -```shell |
68 | | -it-depends /path/to/project |
69 | | -``` |
70 | | - |
71 | | -or alternatively specify a package from a public package repository: |
72 | | - |
73 | | -```shell |
74 | | -it-depends "pip:numpy" |
75 | | -it-depends "ubuntu:libc6@2.31" |
76 | | -it-depends "npm:lodash@>=4.17.0" |
77 | 22 | ``` |
78 | 23 |
|
79 | | -To list resolvers compatible for the specified target, use the `--list` option: |
| 24 | +Ecosystem-specific tools must be installed separately: `npm` for JavaScript, `cargo` for Rust, `pip` for Python, `autotools`/`cmake` for C/C++. Native dependency resolution and Ubuntu package analysis require a Docker-compatible container runtime with an accessible socket (_e.g._, Docker Desktop, Podman, or Colima). |
80 | 25 |
|
81 | | -```shell |
82 | | -it-depends . --list |
83 | | -``` |
84 | | - |
85 | | -It-Depends will output the full dependency hierarchy in JSON format. Additional output formats such |
86 | | -as Graphviz/Dot are available via the `--output-format` option. |
87 | | - |
88 | | -It-Depends can automatically try to match packages against the [OSV vulnerability database](https://osv.dev/) with the |
89 | | -`--audit` option. This is a best-effort matching as it is based on package names, which might not always consistent. |
90 | | -Any discovered vulnerabilities are added to the JSON output. |
91 | | - |
92 | | -It-Depends attempts to parallelize as much of its effort as possible. To limit the maximum number of parallel tasks, use |
93 | | -the `--max-workers` option. |
94 | | - |
95 | | -By default, It-Depends recursively resolves all packages' dependencies to construct a complete dependency graph. The |
96 | | -depth of the recursion can be limited using the `--depth-limit` option. For example, |
| 26 | +## Usage |
97 | 27 |
|
98 | 28 | ```shell |
99 | | -it-depends pip:graphtage --depth-limit 1 |
| 29 | +it-depends . # Analyze current directory |
| 30 | +it-depends /path/to/project # Analyze a source repository |
| 31 | +it-depends "pip:numpy" # Analyze a pip package |
| 32 | +it-depends "ubuntu:libc6@2.31" # Analyze an Ubuntu package |
| 33 | +it-depends "npm:lodash@>=4.17.0" # Specify a version constraint |
| 34 | +it-depends --audit pip:numpy # Include vulnerability audit |
| 35 | +it-depends . --list # List compatible resolvers |
| 36 | +it-depends --output-format dot . # Output as Graphviz/Dot |
| 37 | +it-depends --depth-limit 1 pip:numpy # Only direct dependencies |
100 | 38 | ``` |
101 | 39 |
|
102 | | -will only enumerate the direct dependencies of Graphtage. |
103 | | - |
104 | | -### Examples |
105 | | - |
106 | | -Here is an example of running It-Depends on its own source repository: |
107 | | - |
108 | | - |
109 | | -This is the resulting [json](https://gist.github.com/feliam/2bdec76f7aa50602869059bfa14df156) |
110 | | -with all the discovered dependencies. |
111 | | -This is the resulting [Graphviz dot file](https://gist.github.com/feliam/275951f5788c23a477bc7cf758a32cc2) |
112 | | -producing this |
113 | | - |
114 | | - |
115 | | -This is the resulting dependency graph: |
116 | | - |
117 | | - |
118 | | -### It-Depends' Dependencies |
119 | | - |
120 | | -* JavaScript requires `npm` |
121 | | -* Rust requires `cargo` |
122 | | -* Python requires `pip` |
123 | | -* C/C++ requires `autotools` and/or `cmake` |
124 | | -* Several native dependencies are resolved using Ubuntu’s file to path database `apt-file`, but this is seamlessly handled through an Ubuntu `docker` container on other distributions and operating systems |
125 | | -* Currently `docker` is used to resolve native dependencies |
126 | | - |
127 | 40 | ## Development |
128 | 41 |
|
129 | 42 | ```shell |
130 | 43 | git clone https://github.com/trailofbits/it-depends |
131 | 44 | cd it-depends |
132 | 45 | make dev |
133 | 46 | uv run it-depends --help |
134 | | -``` |
135 | | - |
136 | | -Format and lint code before contributing |
137 | | - |
138 | | -```shell |
139 | 47 | make format lint |
140 | 48 | ``` |
141 | 49 |
|
|
0 commit comments