Python Remediation Suite

The Python remediation suite turns each remediation section into a concrete tool command. It does not replace scanners, ticketing systems, source control, or human reviewers. It creates the bounded packet an agent or orchestrator needs before work starts:

• the selected remediation domain,
• imported recipes from this site,
• enterprise tooling compatibility notes,
• allowed actions,
• stop conditions,
• evidence requirements,
• an agent handoff prompt,
• optional LLM-assist configuration.

Dashboard container and UI

The suite now ships with a browser workbench that sits on top of the same Python planner. The UI lets an operator:

• choose a remediation domain;
• paste free-text, JSON, or SARIF findings;
• configure recipe source, tooling hints, ecosystem, and LLM mode;
• save non-secret access and context notes inside a mounted state directory;
• generate a remediation packet and inspect the JSON plus agent handoff prompt;
• download the latest packet for CI, SOAR, ticketing, or agent handoff.

Build the dashboard image from this repo:

docker build -f Dockerfile.remediation-suite-ui -t security-recipes-suite-ui .

Run it:

docker run --rm -p 8787:8787 \
  -v "$(pwd)/tmp/remediation-suite-ui:/data" \
  -e OPENAI_API_KEY="$OPENAI_API_KEY" \
  security-recipes-suite-ui

Open http://localhost:8787. The container starts:

python scripts/security_recipes_remediation_suite.py serve-dashboard \
  --host 0.0.0.0 \
  --port 8787 \
  --state-dir /data

Useful runtime environment variables:

Health endpoint:

GET /api/health

Install from this repo

The suite uses the Python standard library. From a checkout of security-recipes.ai:

python scripts/security_recipes_remediation_suite.py list-domains

Start the local dashboard without Docker:

python scripts/security_recipes_remediation_suite.py serve-dashboard

Run a domain-specific tool:

python scripts/security_recipes_remediation_suite.py deps \
  --finding dependabot-alert.json \
  --recipes-source public/api/recipes.json \
  --tooling github,snyk,jira \
  --ecosystem npm \
  --llm-mode prompt \
  --output out/deps-packet.json

The same suite works from CI, SOAR, a ticket webhook, a scheduled scanner job, or an agent handoff. The command writes a JSON remediation packet by default. Use --finding - to read a free-text, generic JSON, or SARIF finding from standard input.

Tool commands

You can also use the generic command:

python scripts/security_recipes_remediation_suite.py plan \
  --domain auto \
  --finding finding.sarif \
  --recipes-source https://security-recipes.ai/api/recipes.json

--domain auto scores the first finding against the domain registry and chooses the strongest match. For production dispatch, prefer an explicit command when the scanner already knows the finding class.

Import recipes from the site

Every domain can import recipes from the built site or the public endpoint:

--recipes-source public/api/recipes.json
--recipes-source https://security-recipes.ai/api/recipes.json

Agents can also use the MCP server tools when the site is deployed with MCP:

• recipes_search
• recipes_get
• recipes_match_finding

The Python suite does not need MCP to run. It imports the same recipe corpus through JSON so enterprise schedulers and security platforms can use it without embedding a browser or a site-specific client.

Optional LLM assist

LLM assist is opt-in and has three modes:

Example config:

{
  "endpoint": "https://api.openai.com/v1/chat/completions",
  "model": "gpt-5.5",
  "api_key_env": "OPENAI_API_KEY",
  "temperature": 0.2,
  "timeout": 30
}

Run with:

python scripts/security_recipes_remediation_suite.py sast \
  --finding codeql.sarif \
  --recipes-source public/api/recipes.json \
  --llm-config llm.json \
  --llm-mode call

Use prompt mode first in regulated environments. It produces the model prompt without transmitting data, which makes review and redaction easier.

Packet anatomy

Each packet contains:

• classification - domain score and routing rationale.
• findings - normalized finding identity, source, severity, asset, location, and raw evidence.
• recipe_import - recipes matched from /api/recipes.json.
• enterprise_tooling - compatible source control, scanner, ticketing, registry, GRC, SIEM, or platform categories.
• workflow - inputs, allowed actions, stop conditions, evidence, and outputs.
• agent_handoff - a domain-specific prompt with guardrails.
• llm_assist - disabled, prompt-only, or configured model-call metadata.

Enterprise integration pattern

flowchart LR
    A[Scanner or ticket] --> B[Python domain tool]
    B --> C[Import recipes JSON]
    B --> D[Normalize enterprise tooling]
    B --> E{Optional LLM?}
    E -->|off or prompt| F[Packet only]
    E -->|call| G[Configured LLM endpoint]
    F --> H[Agent runner]
    G --> H
    H --> I[PR handoff or TRIAGE.md]
    I --> J[Human review]
    J --> K[Audit evidence]

    classDef source fill:#0a2540,stroke:#00e5ff,color:#f5f7fb;
    classDef gate fill:#2a1040,stroke:#ff4ecb,color:#f5f7fb;
    classDef output fill:#1a2a1a,stroke:#86efac,color:#f5f7fb;
    class A,B,C,D source
    class E,G,J gate
    class F,H,I,K output

The integrations are intentionally broad:

• source control: GitHub, GitLab, Azure DevOps, Bitbucket;
• scanners: CodeQL, Semgrep, SonarQube, Snyk, Wiz, Trivy, Grype, OSV, Gitleaks, TruffleHog, Veracode, Checkmarx, Fortify;
• registries and artifact systems: Artifactory, Nexus, Harbor, ECR, ACR, GAR, Quay, npm, PyPI, Maven, NuGet;
• ticketing and response: Jira, Linear, ServiceNow, PagerDuty, SOAR;
• evidence and audit: Drata, Vanta, Secureframe, ServiceNow GRC, Archer, AuditBoard, SIEM and data warehouse exports.

The suite only shapes the packet. Connector credentials, write access, approval policies, and production actions stay in the enterprise control plane.

Domain reference

python scripts/security_recipes_remediation_suite.py sde \
  --finding finding.json \
  --recipes-source public/api/recipes.json \
  --tooling github,snyk,jira,servicenow \
  --llm-mode prompt \
  --output out/sde-packet.json

python scripts/security_recipes_remediation_suite.py deps \
  --finding finding.json \
  --recipes-source public/api/recipes.json \
  --tooling github,snyk,jira,servicenow \
  --llm-mode prompt \
  --output out/deps-packet.json

python scripts/security_recipes_remediation_suite.py sast \
  --finding finding.json \
  --recipes-source public/api/recipes.json \
  --tooling github,snyk,jira,servicenow \
  --llm-mode prompt \
  --output out/sast-packet.json

python scripts/security_recipes_remediation_suite.py base-image \
  --finding finding.json \
  --recipes-source public/api/recipes.json \
  --tooling github,snyk,jira,servicenow \
  --llm-mode prompt \
  --output out/base-image-packet.json

python scripts/security_recipes_remediation_suite.py cache-purge \
  --finding finding.json \
  --recipes-source public/api/recipes.json \
  --tooling github,snyk,jira,servicenow \
  --llm-mode prompt \
  --output out/cache-purge-packet.json

python scripts/security_recipes_remediation_suite.py recommend \
  --finding finding.json \
  --recipes-source public/api/recipes.json \
  --tooling github,snyk,jira,servicenow \
  --llm-mode prompt \
  --output out/recommend-packet.json

python scripts/security_recipes_remediation_suite.py gate \
  --finding finding.json \
  --recipes-source public/api/recipes.json \
  --tooling github,snyk,jira,servicenow \
  --llm-mode prompt \
  --output out/gate-packet.json

python scripts/security_recipes_remediation_suite.py runtime \
  --finding finding.json \
  --recipes-source public/api/recipes.json \
  --tooling github,snyk,jira,servicenow \
  --llm-mode prompt \
  --output out/runtime-packet.json

python scripts/security_recipes_remediation_suite.py defaults \
  --finding finding.json \
  --recipes-source public/api/recipes.json \
  --tooling github,snyk,jira,servicenow \
  --llm-mode prompt \
  --output out/defaults-packet.json

python scripts/security_recipes_remediation_suite.py crypto-payments \
  --finding finding.json \
  --recipes-source public/api/recipes.json \
  --tooling github,snyk,jira,servicenow \
  --llm-mode prompt \
  --output out/crypto-payments-packet.json

python scripts/security_recipes_remediation_suite.py defi \
  --finding finding.json \
  --recipes-source public/api/recipes.json \
  --tooling github,snyk,jira,servicenow \
  --llm-mode prompt \
  --output out/defi-packet.json

python scripts/security_recipes_remediation_suite.py metrics \
  --finding finding.json \
  --recipes-source public/api/recipes.json \
  --tooling github,snyk,jira,servicenow \
  --llm-mode prompt \
  --output out/metrics-packet.json

python scripts/security_recipes_remediation_suite.py review \
  --finding finding.json \
  --recipes-source public/api/recipes.json \
  --tooling github,snyk,jira,servicenow \
  --llm-mode prompt \
  --output out/review-packet.json

python scripts/security_recipes_remediation_suite.py rollout \
  --finding finding.json \
  --recipes-source public/api/recipes.json \
  --tooling github,snyk,jira,servicenow \
  --llm-mode prompt \
  --output out/rollout-packet.json

python scripts/security_recipes_remediation_suite.py audit \
  --finding finding.json \
  --recipes-source public/api/recipes.json \
  --tooling github,snyk,jira,servicenow \
  --llm-mode prompt \
  --output out/audit-packet.json

Guardrails

• One finding goes into one domain tool.
• A packet can produce a plan, PR handoff, audit packet, or triage note.
• The suite never auto-merges.
• The suite does not mutate cloud, registry, ticketing, source-control, GRC, or payment systems by itself.
• LLM calls are off by default.
• Secrets, private findings, customer data, and source snippets should stay out of --llm-mode call unless your approved boundary permits that transmission.