feat: add automatic OSCAL manifest generation (#2302)

Signed-off-by: Matteo Fari <matteofari06@gmail.com>
Co-authored-by: Lou DeGenaro <lou.degenaro@gmail.com>

Author: MatteoFari

docs/tutorials/cli.md

@@ -627,10 +627,12 @@ The private key is used for signing. Keep it secret. The public key can be share
 ```bash
 trestle sign \
   -f catalog.json \
-  --key private.pem \
+  --private-key private.pem \
   -o catalog.json.dsse
 ```
 
+By default, signing fails if the output envelope already exists. Pass `--overwrite` to replace an existing envelope.
+
 For an encrypted private key, use `--key-password-env`. The option names an environment variable that contains the password, so the password is not passed as a command-line argument.
 
 ```bash
@@ -640,7 +642,7 @@ openssl pkey -in private-encrypted.pem -passin env:TRESTLE_KEY_PASSWORD -pubout
 chmod 600 private-encrypted.pem
 trestle sign \
   -f catalog.json \
-  --key private-encrypted.pem \
+  --private-key private-encrypted.pem \
   --key-password-env TRESTLE_KEY_PASSWORD \
   -o catalog.json.dsse
 ```
@@ -664,11 +666,40 @@ trestle verify \
 
 If signing used `--subject-name`, pass the same value during verification.
 
+## `trestle generate-manifest`
+
+Trestle generate-manifest creates a package manifest from any top-level OSCAL JSON model: assessment plan, assessment results, catalog, component definition, mapping collection, plan of action and milestones (POA&M), profile, or system security plan (SSP). It follows the model's local and remote OSCAL dependencies recursively and records normalized artifact paths relative to the generated manifest. Catalogs have no further dependencies.
+
+The generate-manifest, sign-manifest, and verify-manifest commands are beta features. Enable them before use:
+
+```bash
+trestle beta enable json-manifest-signing
+```
+
+Generate a manifest from an SSP:
+
+```bash
+trestle generate-manifest \
+  -f system-security-plans/acme/system-security-plan.json \
+  --include component-definitions/web/component-definition.json \
+  -o package.json
+```
+
+By default, generation fails if the output manifest already exists. Pass `--overwrite` to replace an existing manifest.
+
+Use `--include` for other OSCAL JSON files that are part of the package but cannot be inferred from the primary model. Multiple files may be supplied as a comma-separated list. For example, component definitions require explicit inclusion when the primary model is an SSP because SSP assembly does not retain their source paths.
+
+Discovery follows assessment-results to assessment-plan, assessment-plan and POA&M to SSP, SSP to profile or catalog, profile to profile or catalog, component-definition imports and control-implementation sources, and mapping-collection to its declared catalog or profile resources. Local dependencies must stay inside the directory containing the output manifest.
+
+HTTPS and SFTP dependency references are fetched using Trestle's remote cache and copied as canonical JSON into the package's `remote` directory. Relative references in downloaded documents are resolved against their original remote URI. Review the generated manifest and downloaded artifacts before signing them.
+
+Automatic discovery accepts at most 1,000 artifacts, 64 dependency levels, 50 MiB per remote artifact, and 500 MiB of remote artifacts in total. Loopback, link-local, cloud metadata, and private network endpoints are blocked. Use `--allow-private-uris` only when dependencies are hosted on a trusted private network. Loopback, link-local, and cloud metadata endpoints remain blocked when the option is used.
+
 ## `trestle sign-manifest`
 
 Trestle sign-manifest writes a detached DSSE envelope for a JSON package manifest. The manifest lists related JSON artifacts. Trestle canonicalizes each artifact using RFC 8785, records each SHA-256 digest in an in-toto Statement, and signs the package Statement with a PEM private key.
 
-The sign-manifest and verify-manifest commands are beta features. Enable them before use:
+Enable the package manifest beta feature before use:
 
 ```bash
 trestle beta enable json-manifest-signing
@@ -708,10 +739,12 @@ Sign the package manifest:
 ```bash
 trestle sign-manifest \
   --manifest package.json \
-  --key private.pem \
+  --private-key private.pem \
   -o package.dsse
 ```
 
+By default, manifest signing fails if the output envelope already exists. Pass `--overwrite` to replace an existing envelope.
+
 For an encrypted private key, use `--key-password-env` as with `trestle sign`.
 
 The signed package Statement uses the [OSCAL package predicate](../predicates/oscal-package/v1.md).

tests/trestle/core/commands/beta_test.py

@@ -155,6 +155,18 @@ def test_beta_query_global_verbose_does_not_show_details(monkeypatch: MonkeyPatc
     assert 'Description: Sample beta feature' not in output
 
 
+def test_beta_query_aligns_feature_descriptions(monkeypatch: MonkeyPatch, capsys: CaptureFixture[str]) -> None:
+    """Test query aligns descriptions after feature names of different lengths."""
+    patch_beta_features(monkeypatch, sample_feature('short'), sample_feature('much-longer-feature-name'))
+    monkeypatch.setenv(beta_features.TRESTLE_BETA_FEATURES_ENV, 'short,much-longer-feature-name')
+
+    execute_command_and_assert('trestle beta query', CmdReturnCodes.SUCCESS.value, monkeypatch)
+
+    output, _ = capsys.readouterr()
+    feature_lines = [line for line in output.splitlines() if line.startswith('  [enabled]')]
+    assert len({line.index('Sample beta feature') for line in feature_lines}) == 1
+
+
 def test_beta_unknown_feature(monkeypatch: MonkeyPatch, capsys: CaptureFixture[str]) -> None:
     """Test enabling an unknown beta feature fails."""
     patch_beta_features(monkeypatch, sample_feature())

tests/trestle/core/commands/generate_manifest_test.py

@@ -0,0 +1,221 @@
+# -*- mode:python; coding:utf-8 -*-
+
+# Copyright (c) 2026 The OSCAL Compass Authors. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Tests for trestle generate-manifest command."""
+
+import json
+import pathlib
+import sys
+from typing import Any, Dict, Tuple
+
+import pytest
+from _pytest.monkeypatch import MonkeyPatch
+from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.primitives.asymmetric import ed25519
+
+from tests import test_utils
+
+from trestle.cli import Trestle
+from trestle.common import const
+from trestle.core.commands.common.return_codes import CmdReturnCodes
+from trestle.core.commands.generate_manifest import GenerateManifestCmd
+from trestle.core.commands.sign_manifest import SignManifestCmd
+from trestle.core.commands.verify_manifest import VerifyManifestCmd
+from trestle.core.signing_manifest import load_signing_manifest
+
+
+@pytest.fixture(autouse=True)
+def enable_json_manifest_signing_beta(monkeypatch: MonkeyPatch) -> None:
+    """Enable automatic package generation for command tests."""
+    monkeypatch.setenv('TRESTLE_BETA_FEATURES', 'json-manifest-signing')
+
+
+def _read_json(path: pathlib.Path) -> Dict[str, Any]:
+    return json.loads(path.read_text(encoding=const.FILE_ENCODING))
+
+
+def _write_json(path: pathlib.Path, data: Dict[str, Any]) -> pathlib.Path:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(data), encoding=const.FILE_ENCODING)
+    return path
+
+
+def _write_test_package(package_root: pathlib.Path) -> Tuple[pathlib.Path, pathlib.Path]:
+    catalog = _read_json(test_utils.JSON_TEST_DATA_PATH / 'minimal_catalog.json')
+    _write_json(package_root / 'catalogs/catalog.json', catalog)
+
+    profile = _read_json(test_utils.JSON_TEST_DATA_PATH / 'simple_test_profile.json')
+    profile['profile']['imports'] = [{'href': '../catalogs/catalog.json', 'include-all': {}}]
+    profile['profile'].pop('back_matter', None)
+    _write_json(package_root / 'profiles/profile.json', profile)
+
+    ssp = _read_json(test_utils.TEST_DIR / 'data/author/ssp/ssp_example.json')
+    ssp['system-security-plan']['import-profile']['href'] = '../../profiles/profile.json'
+    ssp_path = _write_json(package_root / 'system-security-plans/acme/ssp.json', ssp)
+
+    component = _read_json(test_utils.TEST_DIR / 'data/validate/component-definitions/x1/component-definition.json')
+    component_path = _write_json(package_root / 'component-definitions/web/component-definition.json', component)
+    return ssp_path, component_path
+
+
+def _write_ed25519_key_pair(tmp_path: pathlib.Path) -> Tuple[pathlib.Path, pathlib.Path]:
+    private_key = ed25519.Ed25519PrivateKey.generate()
+    private_key_path = tmp_path / 'private.pem'
+    public_key_path = tmp_path / 'public.pem'
+    private_key_path.write_bytes(
+        private_key.private_bytes(
+            encoding=serialization.Encoding.PEM,
+            format=serialization.PrivateFormat.PKCS8,
+            encryption_algorithm=serialization.NoEncryption(),
+        )
+    )
+    public_key_path.write_bytes(
+        private_key.public_key().public_bytes(
+            encoding=serialization.Encoding.PEM, format=serialization.PublicFormat.SubjectPublicKeyInfo
+        )
+    )
+    return private_key_path, public_key_path
+
+
+def test_generate_manifest_requires_beta_feature(tmp_path: pathlib.Path, monkeypatch: MonkeyPatch) -> None:
+    """Generate-manifest should be blocked unless its beta feature is enabled."""
+    monkeypatch.delenv('TRESTLE_BETA_FEATURES', raising=False)
+    monkeypatch.setenv('XDG_CONFIG_HOME', str(tmp_path / 'xdg-config'))
+    monkeypatch.setattr(
+        sys,
+        'argv',
+        ['trestle', 'generate-manifest', '-f', str(tmp_path / 'ssp.json'), '-o', str(tmp_path / 'package.json')],
+    )
+
+    assert Trestle().run() == CmdReturnCodes.COMMAND_ERROR.value
+
+
+def test_generate_manifest_accepts_one_time_beta_and_explicit_include(
+    tmp_path: pathlib.Path, monkeypatch: MonkeyPatch
+) -> None:
+    """The command should generate valid JSON with a one-time beta flag and explicit include."""
+    monkeypatch.delenv('TRESTLE_BETA_FEATURES', raising=False)
+    monkeypatch.setenv('XDG_CONFIG_HOME', str(tmp_path / 'xdg-config'))
+    package_root = tmp_path / 'package'
+    ssp_path, component_path = _write_test_package(package_root)
+    output_path = package_root / 'package.json'
+    monkeypatch.setattr(
+        sys,
+        'argv',
+        [
+            'trestle',
+            'generate-manifest',
+            '--beta',
+            '-f',
+            str(ssp_path),
+            '--include',
+            str(component_path),
+            '--allow-private-uris',
+            '-o',
+            str(output_path),
+        ],
+    )
+
+    assert Trestle().run() == CmdReturnCodes.SUCCESS.value
+    manifest = load_signing_manifest(output_path)
+    assert manifest.primary_artifact == 'system-security-plans/acme/ssp.json'
+    assert [artifact.name for artifact in manifest.artifacts] == [
+        'system-security-plans/acme/ssp.json',
+        'profiles/profile.json',
+        'catalogs/catalog.json',
+        'component-definitions/web/component-definition.json',
+    ]
+    assert not (tmp_path / 'xdg-config').exists()
+
+
+def test_generate_manifest_parses_comma_separated_includes(tmp_path: pathlib.Path, monkeypatch: MonkeyPatch) -> None:
+    """The CLI should pass each comma-separated explicit artifact to discovery."""
+    package_root = tmp_path / 'package'
+    ssp_path, first_component = _write_test_package(package_root)
+    second_component = package_root / 'component-definitions/database/component-definition.json'
+    second_component.parent.mkdir(parents=True)
+    second_component.write_text(first_component.read_text(encoding=const.FILE_ENCODING), encoding=const.FILE_ENCODING)
+    output_path = package_root / 'package.json'
+    monkeypatch.setattr(
+        sys,
+        'argv',
+        [
+            'trestle',
+            'generate-manifest',
+            '-f',
+            str(ssp_path),
+            '--include',
+            f'{first_component},{second_component}',
+            '-o',
+            str(output_path),
+        ],
+    )
+
+    assert Trestle().run() == CmdReturnCodes.SUCCESS.value
+    assert _artifact_names(output_path)[-2:] == [
+        'component-definitions/web/component-definition.json',
+        'component-definitions/database/component-definition.json',
+    ]
+
+
+def test_generate_manifest_overwrites_existing_output(tmp_path: pathlib.Path, monkeypatch: MonkeyPatch) -> None:
+    """The command should replace an existing output only when explicitly requested."""
+    package_root = tmp_path / 'package'
+    ssp_path, _ = _write_test_package(package_root)
+    output_path = package_root / 'package.json'
+    output_path.write_text('{"old":true}', encoding=const.FILE_ENCODING)
+    monkeypatch.setattr(
+        sys, 'argv', ['trestle', 'generate-manifest', '-f', str(ssp_path), '--overwrite', '-o', str(output_path)]
+    )
+
+    assert Trestle().run() == CmdReturnCodes.SUCCESS.value
+    assert _artifact_names(output_path) == [
+        'system-security-plans/acme/ssp.json',
+        'profiles/profile.json',
+        'catalogs/catalog.json',
+    ]
+
+
+def _artifact_names(manifest_path: pathlib.Path) -> list[str]:
+    return [artifact.name for artifact in load_signing_manifest(manifest_path).artifacts]
+
+
+def test_generate_sign_verify_real_nist_package(tmp_path: pathlib.Path) -> None:
+    """A discovered real NIST SSP, profile, and catalog package should sign and verify."""
+    package_root = tmp_path / 'package'
+    ssp_data = _read_json(test_utils.NIST_EXAMPLES / 'ssp/json/ssp-example.json')
+    ssp_data['system-security-plan']['import-profile']['href'] = '../../profiles/nist-low/profile.json'
+    ssp_path = _write_json(package_root / 'system-security-plans/acme/ssp.json', ssp_data)
+
+    profile_data = _read_json(test_utils.JSON_NIST_DATA_PATH / 'NIST_SP-800-53_rev5_LOW-baseline_profile.json')
+    profile_data['profile']['imports'][0]['href'] = '../../catalogs/nist/catalog.json'
+    _write_json(package_root / 'profiles/nist-low/profile.json', profile_data)
+    catalog_data = _read_json(test_utils.JSON_NIST_DATA_PATH / test_utils.JSON_NIST_CATALOG_NAME)
+    _write_json(package_root / 'catalogs/nist/catalog.json', catalog_data)
+
+    manifest_path = package_root / 'package.json'
+    envelope_path = package_root / 'package.dsse'
+    private_key_path, public_key_path = _write_ed25519_key_pair(tmp_path)
+
+    GenerateManifestCmd.generate_manifest(ssp_path, manifest_path)
+    SignManifestCmd.sign_manifest(manifest_path, private_key_path, envelope_path)
+    VerifyManifestCmd.verify_manifest(manifest_path, envelope_path, public_key_path)
+
+    assert _artifact_names(manifest_path) == [
+        'system-security-plans/acme/ssp.json',
+        'profiles/nist-low/profile.json',
+        'catalogs/nist/catalog.json',
+    ]
+    assert envelope_path.is_file()