Skip to content

agent-bom remediate Output Contract

Use this page when you need the machine-readable contract for agent-bom remediate.

The command supports:

  • console
  • json
  • markdown

The only format intended as a stable automation contract is json.

Example command

agent-bom remediate -p . --format json --output plan.json

Optional grouping:

agent-bom remediate -p . --format json --server-group --output plan.json

Guarded apply:

agent-bom remediate -p . --apply

Draft PR flow:

agent-bom remediate -p . --apply --open-pr

remediate remains read-only unless --apply is present. The apply path is limited to package CVE dependency updates, refuses dirty worktrees, refuses writes outside the git repo root, writes an audit JSONL event, and validates dependency files before opening a draft PR. SAST, IaC, and credential remediation remain advisory/manual in this command.

Top-level JSON shape

{
  "version": "0.88.6",
  "generated_at": "2026-04-21T12:00:00+00:00",
  "remediation_plan": [],
  "summary": {
    "total_items": 0,
    "fixable": 0,
    "unfixable": 0,
    "p1_count": 0,
    "p2_count": 0,
    "p3_count": 0,
    "p4_count": 0
  }
}

When --server-group is set, one additional top-level field is present:

{
  "server_groups": {
    "jira": ["urllib3", "requests"],
    "github": ["openssl"]
  }
}

When --apply is set with JSON output, one additional top-level field is present:

{
  "apply_result": {
    "dry_run": false,
    "applied": [],
    "skipped": [],
    "backed_up": [],
    "changed_files": [],
    "validation_commands": [],
    "audit_log_path": ".agent-bom/remediation-audit.jsonl",
    "branch_name": null,
    "pr_url": null
  }
}

Per-item schema

Each entry in remediation_plan has this shape:

{
  "package": "requests",
  "ecosystem": "pypi",
  "current_version": "2.28.0",
  "fixed_version": "2.32.0",
  "priority": "P1",
  "action": "",
  "command": "pip install 'requests>=2.32.0'",
  "verify_command": "agent-bom check requests@2.32.0 --ecosystem pypi",
  "max_severity": "high",
  "blast_radius_score": 7.5,
  "impact": 1,
  "vulnerabilities": ["CVE-2024-0001"],
  "affected_agents": ["mac-laptop-1"],
  "exposed_credentials": [],
  "exposed_tools": [],
  "references": ["https://nvd.nist.gov/vuln/detail/CVE-2024-0001"],
  "has_kev": false,
  "ai_risk": false,
  "compliance_tags": {
    "owasp": [],
    "atlas": [],
    "nist": [],
    "owasp_mcp": [],
    "owasp_agentic": [],
    "eu_ai_act": [],
    "nist_csf": [],
    "iso_27001": [],
    "soc2": [],
    "cis": []
  }
}

Stable vs advisory fields

Stable contract

These keys are the supported JSON contract for automation:

  • top level: version, generated_at, remediation_plan, summary
  • optional top level with --server-group: server_groups
  • optional top level with --apply: apply_result
  • item fields:
  • package
  • ecosystem
  • current_version
  • fixed_version
  • priority
  • action
  • command
  • verify_command
  • max_severity
  • blast_radius_score
  • impact
  • vulnerabilities
  • affected_agents
  • exposed_credentials
  • exposed_tools
  • references
  • has_kev
  • ai_risk
  • compliance_tags

Advisory semantics

These values are intentionally advisory and may change as scoring or enrichment improves:

  • item ordering
  • blast_radius_score
  • priority
  • impact
  • suggested command
  • suggested verify_command
  • membership and size of references
  • compliance tag population
  • derived summary counts

Treat the JSON shape as stable, but treat prioritization and enrichment values as versioned security analysis output.

Nullability and empty values

Operators and automation should expect:

  • fixed_version may be null
  • command may be null
  • verify_command may be null
  • arrays may be empty
  • server_groups is absent unless --server-group is used

Empty-plan behavior

If no vulnerabilities are found, JSON output still uses the same top-level shape with:

  • remediation_plan: []
  • all summary counts set to 0

If filters remove every item, the same empty JSON shape is returned.

Output modes

Format Best use Contract strength
console humans in a terminal presentation only
json CI, automation, dashboards, export supported contract
markdown PRs, tickets, review threads presentation only