User Guide Output and Report Formats

Output and Report Formats

Prev: Security, Audit, and SBOM | Up: User Guide | Next: Remote Mode

This page documents file outputs, machine-readable schemas, overwrite behavior, and exit-code details.

Common Output Behavior

Stdout vs file

• SBOM prints to stdout when no output path is resolved.
• Audit prints to stdout when no output path is set.
• Snapshot prints command-output block to stdout when no output path is set.
• test-plugin prints human report to stdout; --report adds JSON file.

Relative paths

Relative output paths are resolved against current working directory.

Parent directories

Exporters create parent directories when needed.

Existing files

SBOM, audit, and snapshot all prompt before overwrite unless force flag is present.

Prompt shape is:

<resolved path> already exists. Overwrite? [y/N]

If answer is not y or Y, command aborts.

SBOM Output

Formats:

• table
• json
• cyclonedx-json

Format resolution:

• explicit --format wins
• otherwise request output path implies cyclonedx-json
• otherwise config.sbom.defaultFormat

Output path resolution:

• request --output wins
• otherwise config.sbom.defaultOutputPath

Table format

Columns are:

• SYSTEM
• NAME
• VERSION
• SOURCE

SOURCE is package sourcePath or - when empty.

Flags affecting table output:

• --wide
• --no-wrap

JSON format

Top-level shape:

{
  "packages": [
    {
      "system": "npm",
      "name": "react",
      "displayName": "react",
      "version": "18.3.1",
      "sourcePath": "",
      "localTarget": false
    }
  ],
  "dependencies": [
    { "from": "npm:react@18.3.1", "to": "npm:loose-envify@1.4.0" }
  ]
}

Notes:

• dependencies section is present only when sbom.includeDependencyEdges = true
• displayName is ReqPack-rendered display label, not raw source field

CycloneDX JSON

Top-level shape:

{
  "bomFormat": "CycloneDX",
  "specVersion": "1.5",
  "version": 1,
  "components": [
    {
      "type": "library",
      "bom-ref": "npm:react@18.3.1",
      "name": "react",
      "version": "18.3.1",
      "purl": "pkg:npm/react@18.3.1",
      "properties": [
        { "name": "reqpack:system", "value": "npm" },
        { "name": "reqpack:sourcePath", "value": "/tmp/react.tgz" },
        { "name": "reqpack:localTarget", "value": "true" }
      ]
    }
  ],
  "dependencies": [
    {
      "ref": "npm:react@18.3.1",
      "dependsOn": ["npm:loose-envify@1.4.0"]
    }
  ]
}

Notes:

• purl is included only when metadata provider can build one
• reqpack:sourcePath and reqpack:localTarget properties appear only when applicable
• dependencies section is omitted when dependency edges are disabled

Audit Output

Formats:

• table
• json
• cyclonedx-vex-json
• sarif

Format resolution:

• explicit --format wins
• otherwise --output path extension decides:
  • .sarif -> sarif
  • all other file outputs -> cyclonedx-vex-json
• otherwise default is table

Exit-code behavior

• without output file, findings cause exit code 1
• with output file, findings are exported and do not fail command by themselves

This matters for CI: file export success is not same thing as “no findings.”

Table format

Columns are:

• SYSTEM
• NAME
• VERSION
• FINDING
• SEVERITY
• SCORE
• trailing MESSAGE column

If there are no findings, output is exactly:

No vulnerabilities or audit findings detected.

JSON format

Top-level shape:

{
  "summary": {
    "packageCount": 3,
    "findingCount": 1
  },
  "packages": [
    {
      "system": "npm",
      "name": "react",
      "displayName": "react",
      "version": "18.3.1",
      "sourcePath": "",
      "localTarget": false,
      "ref": "npm:react@18.3.1"
    }
  ],
  "findings": [
    {
      "id": "GHSA-...",
      "kind": "vulnerability",
      "source": "osv",
      "severity": "high",
      "score": 7.5,
      "message": "...",
      "package": {
        "system": "npm",
        "name": "react",
        "version": "18.3.1"
      }
    }
  ]
}

CycloneDX VEX JSON

Top-level shape:

{
  "bomFormat": "CycloneDX",
  "specVersion": "1.5",
  "version": 1,
  "components": [ ... ],
  "dependencies": [ ... ],
  "vulnerabilities": [
    {
      "id": "GHSA-...",
      "source": { "name": "osv" },
      "ratings": [
        {
          "source": { "name": "osv" },
          "severity": "high",
          "score": 7.5
        }
      ],
      "analysis": {
        "state": "in_triage",
        "detail": "Matched by ReqPack audit from local vulnerability data. Reachability and exploitability were not analyzed."
      },
      "description": "...",
      "affects": [
        { "ref": "npm:react@18.3.1" }
      ]
    }
  ]
}

Notes:

• component section mirrors SBOM-style component emission
• dependencies exists only when sbom.includeDependencyEdges = true
• VEX analysis.detail varies by finding kind such as vulnerability, unresolved version, unsupported ecosystem, sync error

SARIF

Top-level shape:

{
  "version": "2.1.0",
  "$schema": "https://json.schemastore.org/sarif-2.1.0.json",
  "runs": [
    {
      "tool": {
        "driver": {
          "name": "ReqPack",
          "rules": [ ... ]
        }
      },
      "results": [
        {
          "ruleId": "GHSA-...",
          "level": "error",
          "message": { "text": "..." },
          "locations": [
            {
              "physicalLocation": {
                "artifactLocation": {
                  "uri": "pkg:npm:react@18.3.1"
                }
              }
            }
          ],
          "properties": {
            "system": "npm",
            "package": "react",
            "version": "18.3.1",
            "kind": "vulnerability",
            "score": 7.5
          }
        }
      ]
    }
  ]
}

SARIF severity mapping from source:

• sync_error -> error
• critical or high -> error
• medium or low -> warning
• otherwise -> note

Snapshot Output

Snapshot format is always Lua manifest text.

Top-level shape:

-- Generated by ReqPack snapshot
return {
  packages = {
    { system = "apt", name = "curl", version = "8.5.0" },
    { system = "npm", name = "react", version = "18.3.1" },
  },
}

Behavior:

• entries are sorted by system, then name
• if no installed state exists, command still emits warning-style message about history.trackInstalled
• file-output mode also emits structured command summary including output path artifact

test-plugin --report JSON

Human output on stdout looks like:

[PASS] list success
[FAIL] info failure - no fakeExec rule matched command: ...
Cases: 2, Passed: 1, Failed: 1

--report JSON top-level shape:

{
  "plugin": "demo-system",
  "pluginPath": "/abs/path/run.lua",
  "passed": 3,
  "failed": 1,
  "cases": [
    {
      "name": "system fixture list",
      "success": true,
      "message": "",
      "commands": ["demo-pm list"],
      "stdout": ["alpha entry"],
      "stderr": [],
      "events": ["listed"],
      "artifacts": [],
      "eventRecords": [
        { "name": "listed", "payload": "{name=alpha, version=1.2.3}" }
      ]
    }
  ]
}

Case entry fields are:

• name
• success
• message
• commands[]
• stdout[]
• stderr[]
• events[]
• artifacts[]
• eventRecords[] with name and payload

Output Areas Not Yet Finished

Config reports.* exists, and validator policy sees reports.enabled. Current source still marks Validator::generateReport() as skeleton hook, so do not treat it as finished general report-export feature.

Related Pages

• Security, Audit, and SBOM
• Configuration
• Configuration Reference
• Testing Lua Plugins

Prev: Security, Audit, and SBOM | Up: User Guide | Next: Remote Mode