You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Currently, we support the following type of project for automatic dependency resolution.
117
+
118
+
* Java Maven
119
+
* Java Gradle
120
+
* Python (with a Python virtual environment created and packages installed using Python3.11, see :ref:`providing Python virtual environment <python-venv-deps>`.)
However, this will return results based only on the current state of the repository, which as described above, is not what we want to achieve in this tutorial. To perform analyses on other repository states, we need to provide Macaron with the target artifact versions in the form of `PURLs <https://github.com/package-url/purl-spec>`_, or Package URLs, which is a convenient way to encode packages from different ecosystems into the same format.
56
56
@@ -67,7 +67,7 @@ We will start by running the analysis on the latest version, ``1.3.0``, with the
The analysis involves Macaron downloading the contents of the target repository to the configured, or default, ``output`` folder. Results from the analysis, including checks, are stored in the database found at ``output/macaron.db`` (See :ref:`Output Files Guide <output_files_guide>`). Once the analysis is complete, Macaron will also produce a report in the form of a HTML file.
73
73
@@ -101,7 +101,7 @@ Now we should run the next analysis, and then open the new report.
.. note:: By default, Macaron clones the repositories and creates output files under the ``output`` directory. To understand the structure of this directory please see :ref:`Output Files Guide <output_files_guide>`.
71
71
@@ -172,27 +172,17 @@ Let's assume ``/tmp/.django_venv`` is the virtual environment where ``django@5.0
172
172
173
173
.. note:: If you want Macaron to analyze the virtual environment directly to identify the dependencies, we require Python 3.11 to be used to install the package. Alternatively, you can generate the SBOM as instructed :ref:`here <python-sbom>` and pass it to Macaron as input.
174
174
175
-
Run Macaron as follows to analyze ``django`` and its dependencies.
175
+
Run Macaron as follows to analyze ``django`` and its direct dependencies.
By default Macaron only checks the direct dependencies. To turn on recursive dependency analysis, add the following to the ``configurations.ini`` file:
183
-
184
-
.. code-block:: ini
185
-
186
-
[dependency.resolver]
187
-
recursive = True
188
-
189
-
And pass that to the ``analyze`` command:
181
+
Or alternatively, run Macaron as follows to analyze ``django`` and all its transitive dependencies.
Now we can enforce the policy below to ensure that the ``mcn_detect_malicious_metadata_1`` check always passes on ``django`` and its dependencies, indicating that none of the dependencies have malicious behavior.
However, there can be checks in Macaron that are not relevant for the ``io.micronaut/micronaut-core`` artifact.
43
43
For example, the ``mcn_provenance_witness_level_one_1`` check (defined in :class:`ProvenanceWitnessL1Check <macaron.slsa_analyzer.checks.provenance_witness_l1_check.ProvenanceWitnessL1Check>`) is not relevant because ``micronaut-projects/micronaut-core`` generates and publishes :term:`SLSA` provenances and no :term:`Witness` provenances. Therefore, we could exclude this check from running by performing the following steps.
@@ -61,7 +61,7 @@ With these two configuration options, all checks except for the excluded ``mcn_p
This time, the check ``mcn_provenance_witness_level_one_1`` doesn't run. After the ``analyze`` command finishes, we can view the data that Macaron has gathered about the ``micronaut-projects/micronaut-core`` repository at ``v4.3.10`` in an HTML report. Note that the result of the excluded check is not recorded in the Macaron HTML reports, JSON reports, or the database).
The analysis involves Macaron downloading the contents of the target repository to the configured, or default, ``output`` folder. Results from the analysis, including checks, are stored in the database found at ``output/macaron.db`` (See :ref:`Output Files Guide <output_files_guide>`). Once the analysis is complete, Macaron will also produce a report in the form of a HTML file.
Copy file name to clipboardExpand all lines: docs/source/pages/using.rst
+41-17Lines changed: 41 additions & 17 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -17,7 +17,7 @@ Using Macaron
17
17
Analyzing an artifact with a PURL string
18
18
----------------------------------------
19
19
20
-
Macaron can analyze an artifact (and its dependencies) to determine its supply chain security posture. To analyze an artifact, you need to provide the PURL identifier of the artifact:
20
+
Macaron can analyze an artifact to determine its supply chain security posture. To analyze an artifact, you need to provide the PURL identifier of the artifact:
21
21
22
22
.. code-block::
23
23
@@ -51,6 +51,7 @@ To run Macaron on an artifact, we use the following command:
51
51
52
52
./run_macaron.sh analyze -purl <artifact-purl>
53
53
54
+
Macaron can also analyze the package's dependencies. Please see :ref:`automate-deps-resolution`.
54
55
55
56
''''''''''''''''''''''''''''''''''''''
56
57
Automated repository and commit finder
@@ -79,6 +80,7 @@ Within the configuration file under the ``repofinder.java`` header, three option
79
80
- ``repo_pom_paths`` (Values: List of POM tags) - Determines where to search for repository information in the POM files. E.g. scm.url.
80
81
- ``find_parents`` (Values: True or False) - When enabled, the Repository Finding feature will also search for repository URLs in parents POM files of the current dependency.
81
82
83
+
.. note:: Dependency related configurations like ``artifact_repositories`` or ``find_parents`` can affect :ref:`Macaron automatic dependency resolution <automate-deps-resolution>`.
82
84
83
85
.. note:: Finding repositories requires at least one remote call, adding some additional overhead to an analysis run.
84
86
@@ -113,7 +115,7 @@ Analyzing a source code repository
113
115
Analyzing a public GitHub repository
114
116
''''''''''''''''''''''''''''''''''''
115
117
116
-
Macaron can also analyze a public GitHub repository (and potentially the repositories of its dependencies).
118
+
Macaron can also analyze a public GitHub repository.
117
119
118
120
To run Macaron on a GitHub public repository, we use the following command:
119
121
@@ -135,14 +137,6 @@ For example, to analyze the SLSA posture of `micronaut-core <https://github.com/
.. note:: Macaron automatically detects and analyzes **direct** dependencies for Java Maven and Gradle projects. This process might take a while and can be skipped by using the ``--skip-deps`` option.
139
-
140
-
Take the same example as above, to disable analyzing `micronaut-core <https://github.com/micronaut-projects/micronaut-core>`_ direct dependencies, we could use the following command:
.. note:: By default, Macaron would generate report files into the ``output`` directory in the current working directory. To understand the structure of this directory please see :ref:`Output Files Guide <output_files_guide>`.
147
141
148
142
With the example above, the generated output reports can be seen here:
@@ -263,6 +257,32 @@ where ``micronaut-core.cue`` file can contain:
263
257
.. note::
264
258
The provenance expectation is verified via the ``provenance_expectation`` check in Macaron. You can see the result of this check in the HTML or JSON report and see if the provenance found by Macaron meets the expectation CUE file.
265
259
260
+
.. _automate-deps-resolution:
261
+
262
+
------------------------------------
263
+
Analyzing dependencies automatically
264
+
------------------------------------
265
+
266
+
Macaron supports automatically detecting and analyzing dependencies for certain types of projects (:ref:`supported_automatic_deps_resolution`). This feature is disabled by default and can be enabled with the CLI flag ``--deps-depth``.
267
+
268
+
The ``--deps-depth`` flag currently accepts these values:
269
+
270
+
* ``0``: Disable dependency resolution (Default).
271
+
* ``1``: Resolve and analyze direct dependencies.
272
+
* ``inf``: Resolve and analyze all transitive dependencies.
273
+
274
+
For example, to analyze `micronaut-core <https://github.com/micronaut-projects/micronaut-core>`_ and its **direct** dependencies, we could use the following command:
.. note:: This process might take a while. Alternatively, you can help Macaron by providing the dependencies information through : :ref:`an sbom <with-sbom>` or :ref:`a Python virtual environment <python-venv-deps>` (for Python packages only).
285
+
266
286
.. _with-sbom:
267
287
268
288
----------------------
@@ -283,10 +303,12 @@ To run the analysis against that SBOM, run this command:
With ``rest_of_args`` being the arguments to the ``analyze`` command (e.g. ``--branch/-b``, ``--digest/-d`` or ``--skip-deps`` similar to two previous examples).
423
+
With ``rest_of_args`` being the arguments to the ``analyze`` command (e.g. ``--branch/-b``, ``--digest/-d`` similar to two previous examples).
400
424
401
425
The ``--local-repos-path/-lr`` flag tells Macaron to look into ``./boo/foo`` for local repositories. For more information, please see :ref:`Command Line Usage <cli-usage>`.
402
426
@@ -422,7 +446,7 @@ We can run Macaron against the local repository at ``target`` by using this comm
With ``rest_of_args`` being the arguments to the ``analyze`` command (e.g. ``--branch/-b``, ``--digest/-d`` or ``--skip-deps`` similar to two previous examples).
449
+
With ``rest_of_args`` being the arguments to the ``analyze`` command (e.g. ``--branch/-b``, ``--digest/-d`` similar to two previous examples).
426
450
427
451
The ``--local-repos-path/-lr`` flag tells Macaron to look into ``./boo/foo`` for local repositories. For more information, please see :ref:`Command Line Usage <cli-usage>`.
0 commit comments