oracle · behnazh-w · Oct 10, 2025 · Oct 9, 2025 · Oct 10, 2025
@@ -76,15 +76,19 @@ To learn how to define your own checks, see the steps in the [checks documentati
 
 * 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:
 
+* 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.
+
 * 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.
 
 * Jens Dietrich, Tim White, Behnaz Hassanshahi, Paddy Krishnan [Levels of Binary Equivalence for the Comparison of Binaries
-from Alternative Builds](https://arxiv.org/pdf/2410.08427), pre-print on arXiv.
+from Alternative Builds](https://arxiv.org/pdf/2410.08427), ICSME Industry Track 2025.
 
 * 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.
 
 * 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.
 
+* Jens Dietrich and Behnaz Hassanshahi [DALEQ--Explainable Equivalence for Java Bytecode](https://arxiv.org/pdf/2508.01530), ASE Industry Showcase 2025.
+
 ## Security
 
 Please consult the [security guide](./SECURITY.md) for our responsible security vulnerability disclosure process.

@@ -20,73 +20,80 @@ Usage
 .. code-block:: shell
 
     usage: ./run_macaron.sh analyze
-        [-h] [-sbom SBOM_PATH] [-purl PURL] [-rp REPO_PATH] [-b BRANCH]
-        [-d DIGEST] [-pe PROVENANCE_EXPECTATION]
-        [--deps-depth DEPS_DEPTH] [-g TEMPLATE_PATH]
-        [--python-venv PYTHON_VENV]
-        [--local-maven-repo LOCAL_MAVEN_REPO]
+        [-h] [-sbom SBOM_PATH] [-rp REPO_PATH] [-purl PACKAGE_URL]
+        [-b BRANCH] [-d DIGEST] [-pe PROVENANCE_EXPECTATION] [-pf PROVENANCE_FILE]
+        [--deps-depth DEPS_DEPTH] [-g TEMPLATE_PATH] [--python-venv PYTHON_VENV]
+        [--local-maven-repo LOCAL_MAVEN_REPO] [--force-analyze-source]
 
 -------
 Options
 -------
 
 .. option:: -h, --help
 
-	Show this help message and exit
+    Show this help message and exit.
 
 .. option:: -sbom SBOM_PATH, --sbom-path SBOM_PATH
 
-    The path to the SBOM of the analysis target.
+    The path to the Software Bill of Materials (SBOM) of the analysis target.
+    If this option is set, dependency resolution must be enabled by using the
+    `--deps-depth` option.
 
-.. option:: -purl PACKAGE_URL, --package-url PACKAGE_URL
+.. option:: -rp REPO_PATH, --repo-path REPO_PATH
 
-    The PURL string used to uniquely identify the target software component for analysis. Note: this PURL string can be
-    consequently used in the policies passed
-    to the policy engine for the same target.
+    The path to the repository, which can be either local or remote.
 
-.. option:: -rp REPO_PATH, --repo-path REPO_PATH
+.. option:: -purl PACKAGE_URL, --package-url PACKAGE_URL
 
-    The path to the repository, can be local or remote
+    The Package URL (PURL) string used to uniquely identify the target software component for analysis.
+    This PURL string can also be used in the policies passed to the policy engine for the same target.
 
 .. option:: -b BRANCH, --branch BRANCH
 
-    The branch of the repository that we want to checkout. If not set, Macaron will use the default branch
+    The branch of the repository that you want to check out. If not set, Macaron will use the default branch.
 
 .. option:: -d DIGEST, --digest DIGEST
 
-    The digest of the commit we want to checkout in the branch. If not set, Macaron will use the latest commit
+    The digest of the commit you want to check out in the branch. If not set, Macaron will use the latest commit.
 
 .. option:: -pe PROVENANCE_EXPECTATION, --provenance-expectation PROVENANCE_EXPECTATION
 
-    The path to provenance expectation file or directory.
+    The path to the provenance expectation file or directory.
 
 .. option:: -pf PROVENANCE_FILE, --provenance-file PROVENANCE_FILE
 
     The path to the provenance file in in-toto format.
 
 .. option:: --deps-depth DEPS_DEPTH
 
-    The depth of the dependency resolution. 0: disable, 1: direct dependencies, inf: all transitive dependencies. (Default: 0)
+    The depth of the dependency resolution. Possible values are:
+
+    - `0`: Disable dependency resolution.
+    - `1`: Resolve direct dependencies only.
+    - `inf`: Resolve all transitive dependencies (default: `0`).
+
+    **Note**: If `--sbom-path` or `--python-venv` is set, this option must be specified.
 
 .. option:: -g TEMPLATE_PATH, --template-path TEMPLATE_PATH
 
-    The path to the Jinja2 html template (please make sure to use .html or .j2 extensions).
+    The path to the Jinja2 HTML template file. Please ensure that the file has either `.html` or `.j2` extensions.
 
-.. option::  --python-venv PYTHON_VENV
+.. option:: --python-venv PYTHON_VENV
 
     The path to the Python virtual environment of the target software component.
+    If this option is set, dependency resolution must be enabled with `--deps-depth`.
 
 .. option:: --local-maven-repo LOCAL_MAVEN_REPO
 
-    The path to the local .m2 directory. If this option is not used, Macaron will use the default location at $HOME/.m2
+    The path to the local `.m2` Maven repository. If this option is not used, Macaron will use the default location at `$HOME/.m2`.
 
 .. option:: --verify-provenance
 
     Allow the analysis to attempt to verify provenance files as part of its normal operations.
 
 .. option:: --force-analyze-source
 
-    Forces PyPI sourcecode analysis to run regardless of other heuristic results.
+    Forces PyPI source code analysis to run, regardless of other heuristic results.
 
 -----------
 Environment

@@ -0,0 +1,43 @@
+.. Copyright (c) 2025 - 2025, Oracle and/or its affiliates. All rights reserved.
+.. Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/.
+
+.. _gen-build-spec-command-cli:
+
+============================
+Generate Build Specification
+============================
+
+-----------
+Description
+-----------
+
+Generate a build specification for a given software component.
+
+-----
+Usage
+-----
+
+.. code-block:: shell
+
+    usage: ./run_macaron.sh gen-build-spec [-h] -purl PACKAGE_URL --database DATABASE [--output-format OUTPUT_FORMAT]
+
+-------
+Options
+-------
+
+.. option:: -h, --help
+
+    Show this help message and exit.
+
+.. option:: -purl PACKAGE_URL, --package-url PACKAGE_URL
+
+    The PURL (Package URL) string of the software component for which the build specification is to be generated.
+
+.. option:: --database DATABASE
+
+    Path to the database.
+
+.. option:: --output-format OUTPUT_FORMAT
+
+    The desired output format for the build specification. The default format is `rc-buildspec`, which is the Reproducible-Central build specification.
+    Other formats may be available depending on your configuration.
@@ -15,7 +15,8 @@ Usage
 
 .. code-block:: shell
 
-	usage: ./run_macaron.sh [-h] [-V] [-v] [-o OUTPUT_DIR] [-dp DEFAULTS_PATH] [-lr LOCAL_REPOS_PATH] {analyze,dump-defaults,verify-policy} ...
+	usage: ./run_macaron.sh [-h] [-V] [-v] [--disable-rich-output] [-o OUTPUT_DIR] [-dp DEFAULTS_PATH] [-lr LOCAL_REPOS_PATH]
+               				{analyze,dump-defaults,verify-policy,find-source,gen-build-spec} ...
 
 Macaron's CLI has multiple common flags (e.g ``-h``, ``-V``) and different commands (e.g. ``analyze``), which have their own set of flags.
 
@@ -27,27 +28,31 @@ Common Options
 
 .. option:: -h, --help
 
-	Show this help message and exit
+    Show this help message and exit.
 
 .. option:: -V, --version
 
-	Show Macaron's version number and exit
+    Show Macaron's version number and exit.
 
 .. option:: -v, --verbose
 
-	Run Macaron with more debug logs
+    Run Macaron with more debug logs to provide additional information for debugging.
+
+.. option:: --disable-rich-output
+
+    Disable Rich UI output. This will turn off any rich formatting (e.g., colored output, tables, etc.) used in the terminal UI.
 
 .. option:: -o OUTPUT_DIR, --output-dir OUTPUT_DIR
 
-	The output destination path for Macaron
+    The output destination path for Macaron. This is where Macaron will store the results of the analysis.
 
 .. option:: -dp DEFAULTS_PATH, --defaults-path DEFAULTS_PATH
 
-	The path to the defaults configuration file.
+    The path to the defaults configuration file. This file can contain preset values for Macaron's options.
 
 .. option:: -lr LOCAL_REPOS_PATH, --local-repos-path LOCAL_REPOS_PATH
 
-	The directory where Macaron looks for already cloned repositories.
+    The directory where Macaron will look for already cloned repositories. This is useful for reusing locally stored repositories without re-cloning them.
 
 ---------------------
 Environment Variables

@@ -0,0 +1,50 @@
+macaron.build\_spec\_generator.cli\_command\_parser package
+===========================================================
+
+.. automodule:: macaron.build_spec_generator.cli_command_parser
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
+Submodules
+----------
+
+macaron.build\_spec\_generator.cli\_command\_parser.gradle\_cli\_command module
+-------------------------------------------------------------------------------
+
+.. automodule:: macaron.build_spec_generator.cli_command_parser.gradle_cli_command
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
+macaron.build\_spec\_generator.cli\_command\_parser.gradle\_cli\_parser module
+------------------------------------------------------------------------------
+
+.. automodule:: macaron.build_spec_generator.cli_command_parser.gradle_cli_parser
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
+macaron.build\_spec\_generator.cli\_command\_parser.maven\_cli\_command module
+------------------------------------------------------------------------------
+
+.. automodule:: macaron.build_spec_generator.cli_command_parser.maven_cli_command
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
+macaron.build\_spec\_generator.cli\_command\_parser.maven\_cli\_parser module
+-----------------------------------------------------------------------------
+
+.. automodule:: macaron.build_spec_generator.cli_command_parser.maven_cli_parser
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
+macaron.build\_spec\_generator.cli\_command\_parser.unparsed\_cli\_command module
+---------------------------------------------------------------------------------
+
+.. automodule:: macaron.build_spec_generator.cli_command_parser.unparsed_cli_command
+   :members:
+   :show-inheritance:
+   :undoc-members:
@@ -0,0 +1,18 @@
+macaron.build\_spec\_generator.reproducible\_central package
+============================================================
+
+.. automodule:: macaron.build_spec_generator.reproducible_central
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
+Submodules
+----------
+
+macaron.build\_spec\_generator.reproducible\_central.reproducible\_central module
+---------------------------------------------------------------------------------
+
+.. automodule:: macaron.build_spec_generator.reproducible_central.reproducible_central
+   :members:
+   :show-inheritance:
+   :undoc-members:
@@ -0,0 +1,59 @@
+macaron.build\_spec\_generator package
+======================================
+
+.. automodule:: macaron.build_spec_generator
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
+Subpackages
+-----------
+
+.. toctree::
+   :maxdepth: 1
+
+   macaron.build_spec_generator.cli_command_parser
+   macaron.build_spec_generator.reproducible_central
+
+Submodules
+----------
+
+macaron.build\_spec\_generator.build\_command\_patcher module
+-------------------------------------------------------------
+
+.. automodule:: macaron.build_spec_generator.build_command_patcher
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
+macaron.build\_spec\_generator.build\_spec\_generator module
+------------------------------------------------------------
+
+.. automodule:: macaron.build_spec_generator.build_spec_generator
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
+macaron.build\_spec\_generator.jdk\_finder module
+-------------------------------------------------
+
+.. automodule:: macaron.build_spec_generator.jdk_finder
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
+macaron.build\_spec\_generator.jdk\_version\_normalizer module
+--------------------------------------------------------------
+
+.. automodule:: macaron.build_spec_generator.jdk_version_normalizer
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
+macaron.build\_spec\_generator.macaron\_db\_extractor module
+------------------------------------------------------------
+
+.. automodule:: macaron.build_spec_generator.macaron_db_extractor
+   :members:
+   :show-inheritance:
+   :undoc-members:
@@ -57,6 +57,14 @@ macaron.malware\_analyzer.pypi\_heuristics.metadata.one\_release module
    :show-inheritance:
    :undoc-members:
 
+macaron.malware\_analyzer.pypi\_heuristics.metadata.package\_description\_intent module
+---------------------------------------------------------------------------------------
+
+.. automodule:: macaron.malware_analyzer.pypi_heuristics.metadata.package_description_intent
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
 macaron.malware\_analyzer.pypi\_heuristics.metadata.similar\_projects module
 ----------------------------------------------------------------------------
 
@@ -73,6 +81,22 @@ macaron.malware\_analyzer.pypi\_heuristics.metadata.source\_code\_repo module
    :show-inheritance:
    :undoc-members:
 
+macaron.malware\_analyzer.pypi\_heuristics.metadata.stub\_name module
+---------------------------------------------------------------------
+
+.. automodule:: macaron.malware_analyzer.pypi_heuristics.metadata.stub_name
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
+macaron.malware\_analyzer.pypi\_heuristics.metadata.type\_stub\_file module
+---------------------------------------------------------------------------
+
+.. automodule:: macaron.malware_analyzer.pypi_heuristics.metadata.type_stub_file
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
 macaron.malware\_analyzer.pypi\_heuristics.metadata.typosquatting\_presence module
 ----------------------------------------------------------------------------------