Myrmica Assimilis - Generate OSS Attribution Files

Description

Generate third-party attribution artifacts (NOTICE + "Third Party Licenses" HTML) from a CycloneDX JSON SBOM.

It is intended to be used in CI/CD to produce release artifacts that can be shipped alongside binaries/images.

Output

By default, it writes:

• third_party/THIRD_PARTY_LICENSES.html: grouped by license, with license texts and "used by" list. Based on cargo-about (default example available here)
• third_party/NOTICE.md: per-dependency copyright/notice block (only for deps that expose copyright)
• third_party/licenses/*.txt: cached SPDX license texts

Usage

1. Place the SBOM in third_party/sbom

   By default, Assimilis looks for third_party/sbom/<REPO_NAME>.cdx.json. The SBOM must have this exact naming pattern.

2. Run Assimilis

   From your repository root:

   assimilis --repo-name <REPO_NAME>

Fetching an SBOM from Aikido

Assimilis can fetch the CycloneDX SBOM from Aikido before generating the attribution files. The Aikido client credentials are read only from the environment:

export AIK_CLIENT=<CLIENT_ID>
export AIK_SECRET=<CLIENT_SECRET>

assimilis fetch \
  --repo-name <REPO_NAME> \
  --repo-code <AIKIDO_REPOSITORY_CODE>

--repo-code can also be set through AIKIDO_REPO_CODE. AIKIDO_BASE_URL optionally overrides the default https://app.aikido.dev API URL.

The command writes the SBOM to third_party/sbom/<REPO_NAME>.cdx.json, generates the normal attribution files, and updates third_party/.last_generated_at only after generation succeeds.

Configuration

NAME:
   assimilis - Generate OSS attribution files

USAGE:
   assimilis [global options] [command [command options]]

COMMANDS:
   version  Display version information
   help, h  Shows a list of commands or help for one command

GLOBAL OPTIONS:
   --repo-name string          Name of the repository
   --output-dir string         Base output directory (default: "third_party")
   --html-template string      Override HTML template path (default: embedded)
   --notice-template string    Override NOTICE template path (default: embedded)
   --spdx-version string       SPDX license-list-data version/tag (default: "v3.27.0")
   --html-filename string      Output HTML filename (default: "THIRD_PARTY_LICENSES.html")
   --notice-filename string    Output NOTICE filename (default: "NOTICE.md")
   --license-map string        Path to external license-map JSON (default: embedded)
   --license-corrections string   Path to external license-corrections JSON (default: embedded)
   --filters string            Path to external filters JSON (default: embedded)
   --help, -h                  show help

License Map

Assimilis ships with an embedded license-map.json that normalizes non-standard license expressions to SPDX IDs (e.g. "Python Software Foundation License" → "PSF-2.0"). To provide your own, use --license-map path/to/license-map.json.

Missing Licenses

Assimilis can apply per-PURL license corrections via license-corrections.json. Entries take priority over whatever the SBOM reported, so they can both fill in absent licenses (when the SBOM generator failed to detect one) and correct wrong ones (when the SBOM generator reported an incorrect license). The embedded license-corrections.json covers known gaps. To provide your own, use --license-corrections path/to/license-corrections.json.

Example:

{
    "pkg:golang/std": "BSD-3-Clause",
    "pkg:npm/config-chain": "MIT"
}

Keys are matched as PURL prefixes — "pkg:golang/std" matches "pkg:golang/[email protected]", and "pkg:golang/github.com/foo/bar" matches sub-packages like "pkg:golang/github.com/foo/bar/v2/[email protected]".

Custom/Non-SPDX Licenses (LicenseRef-*)

If a component uses a non-SPDX license ID or an unmapped license expression, Assimilis expects a corresponding license text file in third_party/licenses/custom.

Example:

third_party/licenses/custom/LicenseRef-<CUSTOM_LICENSE_NAME>.txt

If the text is missing, generation fails.

The Mymirca colony

• Myrmica Lobicornis 🐜: Update and merge pull requests.
• Myrmica Aloba 🐜: Add labels and milestone on pull requests and issues.
• Messor Structor 🐜: Manage multiple documentation versions with Mkdocs.
• Lasius Mixtus 🐜: Publish documentation to a GitHub repository from another.
• Myrmica Bibikoffi 🐜: Closes stale issues
• Chalepoxenus Kutteri 🐜: Track a GitHub repository and publish on Slack.
• Myrmica Gallienii 🐜: Keep Forks Synchronized