Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 33 additions & 0 deletions .github/workflows/tests.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
name: Tests

on:
push:
pull_request:
workflow_dispatch:

permissions:
contents: read

jobs:
test:
name: Python ${{ matrix.python }} on ${{ matrix.os }}
runs-on: ${{ matrix.os }}
timeout-minutes: 10
strategy:
fail-fast: false
matrix:
os: [ubuntu-latest, windows-latest, macos-latest]
python: ['3.10', '3.14']
steps:
- name: Check out repository
uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
with:
persist-credentials: false
- name: Set up Python
uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
with:
python-version: ${{ matrix.python }}
- name: Run local-only tests
run: python -m unittest -v
- name: Check CLI help
run: python oci_runtime_inventory.py --help
131 changes: 124 additions & 7 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,12 +1,129 @@
# oci-runtime-inventory

Optional offline image/SBOM metadata inventory for the checker family tracked in
Standalone Python 3.10+ standard-library inventory for explicit local OCI-layout
or Docker-save archives and supported SBOM JSON. It never runs Docker, executes
an image/binary/package, extracts archive paths onto the host, follows archive
links, opens a network connection or guesses runtime versions from tags/names.
This optional supporting tool addresses
[node2shell-check #12](https://github.com/completetech-security/node2shell-check/issues/12).
The implementation is prepared for review in the initial implementation PR.
No production image, customer inventory or runtime assessment is included.
No exploit checker requires it at runtime.

The tool is not a mandatory dependency of any exploit checker. The approved
implementation will remain standalone Python 3.10+, standard library only,
without image execution, archive extraction or network access.
```sh
python oci_runtime_inventory.py --archive authorized-image.tar --output image-inventory.json
python oci_runtime_inventory.py --sbom examples/inventory.sbom.json
python oci_runtime_inventory.py --archive authorized-image.tar --consumer sharp --output sharp-input.json
python oci_runtime_inventory.py --archive authorized-image.tar --consumer node2shell --output node-input.json
python oci_runtime_inventory.py --sbom examples/inventory.sbom.json --consumer flowise --output flowise-input.json
python -m unittest -v
```

See AGENTS.md, CONTRIBUTING.md, SECURITY.md, LICENSING.md and BRAND_ASSETS.md.
The checked-in SBOM is synthetic. Real images, inventories and reports must stay
outside version control. Only read images/evidence you are authorized to inspect.
`--output` refuses existing files unless `--force` is explicit, and always protects
inputs, aliases and the executable. No installed dependencies or companion files
are required when the Python entry point is copied alone.

## Evidence and uncertainty

Canonical JSON schema 1.0 records supported parsing coverage, limits/usage,
artifact identities, layer digests and logical file provenance. OCI identities
are verified manifest digests; Docker-save identities are config-byte digests
(`identity_kind` distinguishes them). An OCI manifest digest binds its declared layer descriptors. A Docker-save
config digest identifies only config bytes and does not bind the archive layers:
`rootfs.diff_ids` are not validated, and identical configs with different supplied
layers retain the same config digest. Use the separately recorded ordered layer
digests when comparing observations. Neither identity establishes publisher trust
or that an archive can run. Config Env/Cmd/hostnames and image
tags are not reported. SBOM digests identify the SBOM artifact, not an image.

The virtual filesystem applies layers in order. Whiteouts remove lower-layer
entries; opaque whiteouts retain same-layer additions regardless of TAR ordering.
Replaced/deleted manifests cannot survive as current package observations.
Links and device entries are opaque replacement nodes, never followed or created.
Metadata under a nondirectory ancestor, or a selected metadata path that is a
link/device/directory, makes image coverage incomplete.

Exact versions come only from selected package manifests (Sharp, Flowise and
flowise-components) or Node.js package-database records (dpkg/APK). Installed
package metadata does not attest deployed runtime use, bundled/global native
linkage, vendor patches or custom builds. No filename/tag/binary-string inference
is performed. All local exploitability remains `not_tested`; no vulnerability or
safety verdict is produced. No observation is proof of absence.

`--consumer node2shell|sharp|flowise` emits actual input contracts for those
standalone checkers. Unverified provenance/library selection is retained, so
metadata alone produces unknown assessments. Qualified/oversized/control-bearing
versions are never normalized into patch claims. Incomplete images are excluded
from consumer records; absent supported records produce unknown placeholders,
not empty evidence presented as a clean scan. Canonical output retains the full
coverage/provenance record; consumer output intentionally carries only each
checker's accepted fields. Preserve the process exit code as well as the output.

## Supported formats and bounds

- Uncompressed outer USTAR/V7 TAR containing OCI image-layout 1.0 or Docker-save
manifest/config/layers. Regular GNU members work when they fit basic header
fields. No host filesystem extraction is used. SHA-256 OCI manifest/config/layer
descriptors and declared blob sizes are checked; descriptor URLs are never used.
- OCI plain-TAR or gzip layers; Docker-save plain-TAR layers. Extended PAX/GNU
long-name/sparse records, zstd, foreign layers, unsupported digests, outer gzip
and other archive formats are unresolved, not silently accepted as complete.
- JSON CycloneDX 1.4/1.5/1.6, including metadata.component and nested components;
SPDX 2.2/2.3 package metadata. This reads selected metadata fields, not full SBOM
conformance or deployment/relationship attestation.
- Default 512 MiB expanded layer bytes; `--max-expanded-mib` accepts 16-4096.
Other limits: 8 GiB outer archive, 1 GiB compressed layer reads, 100,000 archive
and layer members, 64 path components/512 path characters, 16 images, 256
layers/image, 64 index descriptors and three nested indexes, 4 MiB metadata
files, 16 MiB aggregate captured metadata, 10,000 visited SBOM component entries (including irrelevant entries) and
10,000 selected component records per image,
100 SBOM inputs, bounded JSON depth/node count and at most 1 MiB TAR tail padding.

Unsupported/malformed input, integrity mismatch or any limit marks coverage
incomplete with a symbolic reason and exits 2 while preserving completed images.
No components from a failed image are emitted. Exit 0 means supported inspection
completed, not that a runtime is safe. Interruption exits 130 and preserves
completed observations before output begins when possible. Once stdout or atomic
file publication starts, it is never retried; inspect interrupted output before
running again. Ordinary regular-file/path checks assume stable evidence copies
and are not a sandbox against concurrent filesystem mutation.

## Validation and provenance

Tests use synthetic archives only. They cover layer replacement/deletion,
whiteout ordering, links/devices, traversal, duplicate/sparse/extended records,
truncation/checksums/digests, expansion limits, metadata privacy, standalone
execution, output aliases and interruption. Real exported consumer payloads were
also accepted by the actual Node2Shell, Sharp and Flowise CLIs with unknown
assessments. Local checks and exact-commit hosted CI are separate evidence.
GitHub Copilot reviews published changes before merge.

Format references reviewed 2026-10-25:
[OCI layout](https://github.com/opencontainers/image-spec/blob/main/image-layout.md),
[OCI layers/whiteouts](https://github.com/opencontainers/image-spec/blob/main/layer.md),
[CycloneDX schema](https://github.com/CycloneDX/specification/blob/master/schema/bom-1.6.schema.json),
[SPDX package metadata](https://spdx.github.io/spdx-spec/v2.3.1/package-information/).
No advisory fix table is embedded: this is supporting inventory, not an exploit
checker. Consumer schemas are pinned by the documented v1 contracts; no feed or
network dependency is introduced.

[AGENTS](AGENTS.md), [contribution terms](CONTRIBUTING.md), [security policy](SECURITY.md),
[AGPL license](LICENSE), [dual licensing](LICENSING.md), [brand policy](BRAND_ASSETS.md).

Consumer exports are bounded by the destination input contract: Sharp 1,000
records/four MiB, Node2Shell 10,000 records/four MiB, Flowise 10,000 records/16 MiB.
An oversized merged export fails before publication; use canonical output or split
the source inputs explicitly. No records are silently truncated. CycloneDX subject
component provenance uses `metadata/component` without an invented array index.

Layer application skips lower-snapshot traversal for empty layers and limits
aggregate lower-snapshot path visits to two million. Per-layer selected-file
ancestor validation examines only new file observations; earlier verified state
is not rescanned for empty layers. Layer trailing padding shares the outer
archive one-MiB cap. OCI indexes require schemaVersion 2. Held dpkg Node packages
retain installed-version metadata. Namespaced CycloneDX packages are not matched
as unscoped Sharp/Flowise/Node names.

Layer reads share a 200,000-call budget, bounding per-byte gzip header processing as well as byte/expansion limits. OCI image planning errors produce an incomplete image record while independently supported sibling images retain their observations. Limits remain shared across images.

Every candidate package.json is captured and strictly parsed before its package name is known. Irrelevant manifests still consume the shared capture budget; malformed or excessive candidates make that image incomplete. These deliberately conservative bounds can reject large valid images/SBOMs. OCI attestation manifests and unsupported layer media types are recorded as incomplete; platform labels are not collected. No-force publication requires hard-link support and fails closed otherwise.
1 change: 1 addition & 0 deletions SHA256SUMS
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
b6422d9849a64a4fe54a316a1d64f3fed4a20f52486697990b1d9bc08e6547f2 oci_runtime_inventory.py
21 changes: 21 additions & 0 deletions examples/inventory.sbom.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
{
"bomFormat": "CycloneDX",
"specVersion": "1.6",
"components": [
{
"type": "library",
"name": "sharp",
"version": "0.35.5"
},
{
"type": "application",
"name": "flowise",
"version": "3.1.3"
},
{
"type": "application",
"name": "nodejs",
"version": "24.22.1-vendor"
}
]
}
Loading
Loading