Skip to content

Commit 298ff6b

Browse files
behnazh-wbehnazh-w
authored
docs: add a tutorial for gen-build-spec (#1208)
This PR adds a tutorial for the new gen-build-spec command and improves the documentation. Signed-off-by: behnazh-w <[email protected]>
1 parent b0c46fa commit 298ff6b

13 files changed

+445
-29
lines changed

‎README.md‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -76,15 +76,19 @@ To learn how to define your own checks, see the steps in the [checks documentati
7676

7777
* Behnaz Hassanshahi, Trong Nhan Mai, Alistair Michael, Benjamin Selwyn-Smith, Sophie Bates, and Padmanabhan Krishnan: [Macaron: A Logic-based Framework for Software Supply Chain Security Assurance](https://dl.acm.org/doi/abs/10.1145/3605770.3625213), SCORED 2023. Best paper award :trophy:
7878

79+
* Behnaz Hassanshahi, Trong Nhan Mai, Benjamin Selwyn-Smith, and Nicholas Allen: [Unlocking Reproducibility: Automating re-Build Process for Open-Source Software](https://arxiv.org/pdf/2509.08204), ASE Industry Showcase 2025.
80+
7981
* Ridwan Shariffdeen, Behnaz Hassanshahi, Martin Mirchev, Ali El Husseini, Abhik Roychoudhury [Detecting Python Malware in the Software Supply Chain with Program Analysis](https://labs.oracle.com/pls/apex/f?p=94065:10:11591088449483:11569), ICSE-SEIP 2025.
8082

8183
* Jens Dietrich, Tim White, Behnaz Hassanshahi, Paddy Krishnan [Levels of Binary Equivalence for the Comparison of Binaries
82-
from Alternative Builds](https://arxiv.org/pdf/2410.08427), pre-print on arXiv.
84+
from Alternative Builds](https://arxiv.org/pdf/2410.08427), ICSME Industry Track 2025.
8385

8486
* Jens Dietrich, Tim White, Valerio Terragni, Behnaz Hassanshahi [Towards Cross-Build Differential Testing](https://labs.oracle.com/pls/apex/f?p=94065:10:11591088449483:11549), ICST 2025.
8587

8688
* Jens Dietrich, Tim White, Mohammad Mahdi Abdollahpour, Elliott Wen, Behnaz Hassanshahi [BinEq-A Benchmark of Compiled Java Programs to Assess Alternative Builds](https://dl.acm.org/doi/10.1145/3689944.3696162), SCORED 2024.
8789

90+
* Jens Dietrich and Behnaz Hassanshahi [DALEQ--Explainable Equivalence for Java Bytecode](https://arxiv.org/pdf/2508.01530), ASE Industry Showcase 2025.
91+
8892
## Security
8993

9094
Please consult the [security guide](./SECURITY.md) for our responsible security vulnerability disclosure process.

‎docs/source/pages/cli_usage/command_analyze.rst‎

Lines changed: 28 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -20,73 +20,80 @@ Usage
2020
.. code-block:: shell
2121
2222
usage: ./run_macaron.sh analyze
23-
[-h] [-sbom SBOM_PATH] [-purl PURL] [-rp REPO_PATH] [-b BRANCH]
24-
[-d DIGEST] [-pe PROVENANCE_EXPECTATION]
25-
[--deps-depth DEPS_DEPTH] [-g TEMPLATE_PATH]
26-
[--python-venv PYTHON_VENV]
27-
[--local-maven-repo LOCAL_MAVEN_REPO]
23+
[-h] [-sbom SBOM_PATH] [-rp REPO_PATH] [-purl PACKAGE_URL]
24+
[-b BRANCH] [-d DIGEST] [-pe PROVENANCE_EXPECTATION] [-pf PROVENANCE_FILE]
25+
[--deps-depth DEPS_DEPTH] [-g TEMPLATE_PATH] [--python-venv PYTHON_VENV]
26+
[--local-maven-repo LOCAL_MAVEN_REPO] [--force-analyze-source]
2827
2928
-------
3029
Options
3130
-------
3231

3332
.. option:: -h, --help
3433

35-
Show this help message and exit
34+
Show this help message and exit.
3635

3736
.. option:: -sbom SBOM_PATH, --sbom-path SBOM_PATH
3837

39-
The path to the SBOM of the analysis target.
38+
The path to the Software Bill of Materials (SBOM) of the analysis target.
39+
If this option is set, dependency resolution must be enabled by using the
40+
`--deps-depth` option.
4041

41-
.. option:: -purl PACKAGE_URL, --package-url PACKAGE_URL
42+
.. option:: -rp REPO_PATH, --repo-path REPO_PATH
4243

43-
The PURL string used to uniquely identify the target software component for analysis. Note: this PURL string can be
44-
consequently used in the policies passed
45-
to the policy engine for the same target.
44+
The path to the repository, which can be either local or remote.
4645

47-
.. option:: -rp REPO_PATH, --repo-path REPO_PATH
46+
.. option:: -purl PACKAGE_URL, --package-url PACKAGE_URL
4847

49-
The path to the repository, can be local or remote
48+
The Package URL (PURL) string used to uniquely identify the target software component for analysis.
49+
This PURL string can also be used in the policies passed to the policy engine for the same target.
5050

5151
.. option:: -b BRANCH, --branch BRANCH
5252

53-
The branch of the repository that we want to checkout. If not set, Macaron will use the default branch
53+
The branch of the repository that you want to check out. If not set, Macaron will use the default branch.
5454

5555
.. option:: -d DIGEST, --digest DIGEST
5656

57-
The digest of the commit we want to checkout in the branch. If not set, Macaron will use the latest commit
57+
The digest of the commit you want to check out in the branch. If not set, Macaron will use the latest commit.
5858

5959
.. option:: -pe PROVENANCE_EXPECTATION, --provenance-expectation PROVENANCE_EXPECTATION
6060

61-
The path to provenance expectation file or directory.
61+
The path to the provenance expectation file or directory.
6262

6363
.. option:: -pf PROVENANCE_FILE, --provenance-file PROVENANCE_FILE
6464

6565
The path to the provenance file in in-toto format.
6666

6767
.. option:: --deps-depth DEPS_DEPTH
6868

69-
The depth of the dependency resolution. 0: disable, 1: direct dependencies, inf: all transitive dependencies. (Default: 0)
69+
The depth of the dependency resolution. Possible values are:
70+
71+
- `0`: Disable dependency resolution.
72+
- `1`: Resolve direct dependencies only.
73+
- `inf`: Resolve all transitive dependencies (default: `0`).
74+
75+
**Note**: If `--sbom-path` or `--python-venv` is set, this option must be specified.
7076

7177
.. option:: -g TEMPLATE_PATH, --template-path TEMPLATE_PATH
7278

73-
The path to the Jinja2 html template (please make sure to use .html or .j2 extensions).
79+
The path to the Jinja2 HTML template file. Please ensure that the file has either `.html` or `.j2` extensions.
7480

75-
.. option:: --python-venv PYTHON_VENV
81+
.. option:: --python-venv PYTHON_VENV
7682

7783
The path to the Python virtual environment of the target software component.
84+
If this option is set, dependency resolution must be enabled with `--deps-depth`.
7885

7986
.. option:: --local-maven-repo LOCAL_MAVEN_REPO
8087

81-
The path to the local .m2 directory. If this option is not used, Macaron will use the default location at $HOME/.m2
88+
The path to the local `.m2` Maven repository. If this option is not used, Macaron will use the default location at `$HOME/.m2`.
8289

8390
.. option:: --verify-provenance
8491

8592
Allow the analysis to attempt to verify provenance files as part of its normal operations.
8693

8794
.. option:: --force-analyze-source
8895

89-
Forces PyPI sourcecode analysis to run regardless of other heuristic results.
96+
Forces PyPI source code analysis to run, regardless of other heuristic results.
9097

9198
-----------
9299
Environment

‎docs/source/pages/cli_usage/command_gen_build_spec.rst‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
.. Copyright (c) 2025 - 2025, Oracle and/or its affiliates. All rights reserved.
2+
.. Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/.
3+
4+
.. _gen-build-spec-command-cli:
5+
6+
============================
7+
Generate Build Specification
8+
============================
9+
10+
-----------
11+
Description
12+
-----------
13+
14+
Generate a build specification for a given software component.
15+
16+
-----
17+
Usage
18+
-----
19+
20+
.. code-block:: shell
21+
22+
usage: ./run_macaron.sh gen-build-spec [-h] -purl PACKAGE_URL --database DATABASE [--output-format OUTPUT_FORMAT]
23+
24+
-------
25+
Options
26+
-------
27+
28+
.. option:: -h, --help
29+
30+
Show this help message and exit.
31+
32+
.. option:: -purl PACKAGE_URL, --package-url PACKAGE_URL
33+
34+
The PURL (Package URL) string of the software component for which the build specification is to be generated.
35+
36+
.. option:: --database DATABASE
37+
38+
Path to the database.
39+
40+
.. option:: --output-format OUTPUT_FORMAT
41+
42+
The desired output format for the build specification. The default format is `rc-buildspec`, which is the Reproducible-Central build specification.
43+
Other formats may be available depending on your configuration.

‎docs/source/pages/cli_usage/index.rst‎

Lines changed: 12 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,8 @@ Usage
1515

1616
.. code-block:: shell
1717
18-
usage: ./run_macaron.sh [-h] [-V] [-v] [-o OUTPUT_DIR] [-dp DEFAULTS_PATH] [-lr LOCAL_REPOS_PATH] {analyze,dump-defaults,verify-policy} ...
18+
usage: ./run_macaron.sh [-h] [-V] [-v] [--disable-rich-output] [-o OUTPUT_DIR] [-dp DEFAULTS_PATH] [-lr LOCAL_REPOS_PATH]
19+
{analyze,dump-defaults,verify-policy,find-source,gen-build-spec} ...
1920
2021
Macaron's CLI has multiple common flags (e.g ``-h``, ``-V``) and different commands (e.g. ``analyze``), which have their own set of flags.
2122

@@ -27,27 +28,31 @@ Common Options
2728

2829
.. option:: -h, --help
2930

30-
Show this help message and exit
31+
Show this help message and exit.
3132

3233
.. option:: -V, --version
3334

34-
Show Macaron's version number and exit
35+
Show Macaron's version number and exit.
3536

3637
.. option:: -v, --verbose
3738

38-
Run Macaron with more debug logs
39+
Run Macaron with more debug logs to provide additional information for debugging.
40+
41+
.. option:: --disable-rich-output
42+
43+
Disable Rich UI output. This will turn off any rich formatting (e.g., colored output, tables, etc.) used in the terminal UI.
3944

4045
.. option:: -o OUTPUT_DIR, --output-dir OUTPUT_DIR
4146

42-
The output destination path for Macaron
47+
The output destination path for Macaron. This is where Macaron will store the results of the analysis.
4348

4449
.. option:: -dp DEFAULTS_PATH, --defaults-path DEFAULTS_PATH
4550

46-
The path to the defaults configuration file.
51+
The path to the defaults configuration file. This file can contain preset values for Macaron's options.
4752

4853
.. option:: -lr LOCAL_REPOS_PATH, --local-repos-path LOCAL_REPOS_PATH
4954

50-
The directory where Macaron looks for already cloned repositories.
55+
The directory where Macaron will look for already cloned repositories. This is useful for reusing locally stored repositories without re-cloning them.
5156

5257
---------------------
5358
Environment Variables

‎docs/source/pages/developers_guide/apidoc/macaron.build_spec_generator.cli_command_parser.rst‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
macaron.build\_spec\_generator.cli\_command\_parser package
2+
===========================================================
3+
4+
.. automodule:: macaron.build_spec_generator.cli_command_parser
5+
:members:
6+
:show-inheritance:
7+
:undoc-members:
8+
9+
Submodules
10+
----------
11+
12+
macaron.build\_spec\_generator.cli\_command\_parser.gradle\_cli\_command module
13+
-------------------------------------------------------------------------------
14+
15+
.. automodule:: macaron.build_spec_generator.cli_command_parser.gradle_cli_command
16+
:members:
17+
:show-inheritance:
18+
:undoc-members:
19+
20+
macaron.build\_spec\_generator.cli\_command\_parser.gradle\_cli\_parser module
21+
------------------------------------------------------------------------------
22+
23+
.. automodule:: macaron.build_spec_generator.cli_command_parser.gradle_cli_parser
24+
:members:
25+
:show-inheritance:
26+
:undoc-members:
27+
28+
macaron.build\_spec\_generator.cli\_command\_parser.maven\_cli\_command module
29+
------------------------------------------------------------------------------
30+
31+
.. automodule:: macaron.build_spec_generator.cli_command_parser.maven_cli_command
32+
:members:
33+
:show-inheritance:
34+
:undoc-members:
35+
36+
macaron.build\_spec\_generator.cli\_command\_parser.maven\_cli\_parser module
37+
-----------------------------------------------------------------------------
38+
39+
.. automodule:: macaron.build_spec_generator.cli_command_parser.maven_cli_parser
40+
:members:
41+
:show-inheritance:
42+
:undoc-members:
43+
44+
macaron.build\_spec\_generator.cli\_command\_parser.unparsed\_cli\_command module
45+
---------------------------------------------------------------------------------
46+
47+
.. automodule:: macaron.build_spec_generator.cli_command_parser.unparsed_cli_command
48+
:members:
49+
:show-inheritance:
50+
:undoc-members:

‎docs/source/pages/developers_guide/apidoc/macaron.build_spec_generator.reproducible_central.rst‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
macaron.build\_spec\_generator.reproducible\_central package
2+
============================================================
3+
4+
.. automodule:: macaron.build_spec_generator.reproducible_central
5+
:members:
6+
:show-inheritance:
7+
:undoc-members:
8+
9+
Submodules
10+
----------
11+
12+
macaron.build\_spec\_generator.reproducible\_central.reproducible\_central module
13+
---------------------------------------------------------------------------------
14+
15+
.. automodule:: macaron.build_spec_generator.reproducible_central.reproducible_central
16+
:members:
17+
:show-inheritance:
18+
:undoc-members:

‎docs/source/pages/developers_guide/apidoc/macaron.build_spec_generator.rst‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
macaron.build\_spec\_generator package
2+
======================================
3+
4+
.. automodule:: macaron.build_spec_generator
5+
:members:
6+
:show-inheritance:
7+
:undoc-members:
8+
9+
Subpackages
10+
-----------
11+
12+
.. toctree::
13+
:maxdepth: 1
14+
15+
macaron.build_spec_generator.cli_command_parser
16+
macaron.build_spec_generator.reproducible_central
17+
18+
Submodules
19+
----------
20+
21+
macaron.build\_spec\_generator.build\_command\_patcher module
22+
-------------------------------------------------------------
23+
24+
.. automodule:: macaron.build_spec_generator.build_command_patcher
25+
:members:
26+
:show-inheritance:
27+
:undoc-members:
28+
29+
macaron.build\_spec\_generator.build\_spec\_generator module
30+
------------------------------------------------------------
31+
32+
.. automodule:: macaron.build_spec_generator.build_spec_generator
33+
:members:
34+
:show-inheritance:
35+
:undoc-members:
36+
37+
macaron.build\_spec\_generator.jdk\_finder module
38+
-------------------------------------------------
39+
40+
.. automodule:: macaron.build_spec_generator.jdk_finder
41+
:members:
42+
:show-inheritance:
43+
:undoc-members:
44+
45+
macaron.build\_spec\_generator.jdk\_version\_normalizer module
46+
--------------------------------------------------------------
47+
48+
.. automodule:: macaron.build_spec_generator.jdk_version_normalizer
49+
:members:
50+
:show-inheritance:
51+
:undoc-members:
52+
53+
macaron.build\_spec\_generator.macaron\_db\_extractor module
54+
------------------------------------------------------------
55+
56+
.. automodule:: macaron.build_spec_generator.macaron_db_extractor
57+
:members:
58+
:show-inheritance:
59+
:undoc-members:

‎docs/source/pages/developers_guide/apidoc/macaron.malware_analyzer.pypi_heuristics.metadata.rst‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -57,6 +57,14 @@ macaron.malware\_analyzer.pypi\_heuristics.metadata.one\_release module
5757
:show-inheritance:
5858
:undoc-members:
5959

60+
macaron.malware\_analyzer.pypi\_heuristics.metadata.package\_description\_intent module
61+
---------------------------------------------------------------------------------------
62+
63+
.. automodule:: macaron.malware_analyzer.pypi_heuristics.metadata.package_description_intent
64+
:members:
65+
:show-inheritance:
66+
:undoc-members:
67+
6068
macaron.malware\_analyzer.pypi\_heuristics.metadata.similar\_projects module
6169
----------------------------------------------------------------------------
6270

@@ -73,6 +81,22 @@ macaron.malware\_analyzer.pypi\_heuristics.metadata.source\_code\_repo module
7381
:show-inheritance:
7482
:undoc-members:
7583

84+
macaron.malware\_analyzer.pypi\_heuristics.metadata.stub\_name module
85+
---------------------------------------------------------------------
86+
87+
.. automodule:: macaron.malware_analyzer.pypi_heuristics.metadata.stub_name
88+
:members:
89+
:show-inheritance:
90+
:undoc-members:
91+
92+
macaron.malware\_analyzer.pypi\_heuristics.metadata.type\_stub\_file module
93+
---------------------------------------------------------------------------
94+
95+
.. automodule:: macaron.malware_analyzer.pypi_heuristics.metadata.type_stub_file
96+
:members:
97+
:show-inheritance:
98+
:undoc-members:
99+
76100
macaron.malware\_analyzer.pypi\_heuristics.metadata.typosquatting\_presence module
77101
----------------------------------------------------------------------------------
78102

0 commit comments

Comments
 (0)