Output Formats

SPECTRA produces two output formats: Markdown (human-readable) and JSON (machine-readable for downstream tooling). Both are rendered from the same analysis, so they always contain the same findings. Use --format both to generate both from a single API call.


Format Options

ValueWith --output <path>Without --outputUse case
markdown (default)<path>.mdRendered to the terminalReports, executive briefings, GRC documentation
json<path>.jsonPrinted to stdoutSIEM integration, ticketing automation, dashboards
both<path>.md + <path>.jsonBoth printed, Markdown firstFull reporting plus downstream automation
spectra analyze trivy.json --format both --output reports/scan-2026-05-18
# Writes: reports/scan-2026-05-18.md
#         reports/scan-2026-05-18.json

SPECTRA replaces any extension on the --output path, so --output reports/scan.txt writes reports/scan.md. Missing parent directories are created.

Status messages, the progress spinner and --usage token stats go to stderr, so --format json without --output is safe to pipe:

spectra analyze trivy.json --format json | jq '.overall_risk_score'

Markdown Report Structure

The Markdown report is ordered for a reader who has 30 seconds, then for the engineer who has to fix things. Sections with no content (for example, no attack chains) are left out.

# SPECTRA — Security Intelligence Report
*Analyzed: 2026-11-13 02:16 UTC | Scanner: Semgrep*

---

## ⚠️ Overall Risk: HIGH &nbsp; `84/100`

### Executive Summary

This SAST scan found six code-level weaknesses (no critical, three high, three
medium), led by a string-concatenated SQL query in app/api/users.py ...

### Findings at a Glance

| Severity | Count |
|:---------|------:|
| 🔴 CRITICAL | 0 |
| 🟠 HIGH | 3 |
| 🟡 MEDIUM | 3 |
| 🔵 LOW | 0 |
| ⚪ INFO | 0 |

*6 raw findings → 6 unique after dedup*

---

## ⚡ Immediate Actions Required

1. Fix SPEC-001: parameterize the query in app/api/users.py:47 ...
2. Fix SPEC-002: roll the Stripe secret key in the Stripe Dashboard now ...

## 🔗 Attack Chains

### SQL injection to mass account takeover
*Chained findings: `SPEC-001`, `SPEC-004`*

1) The attacker exploits the concatenated query in users.py (SPEC-001) ...

## Detailed Findings

### 🟠 HIGH — SQL injection via string concatenation in cursor.execute (users.py:47) &nbsp; `SPEC-001`

**Component:** `app/api/users.py:47`  |  **Exploitability:** Requires Access

The `username` value is concatenated directly into a raw SQL string ...

> **Remediation:** Replace the concatenated query with a parameterized one ...

**References:**
- https://cwe.mitre.org/data/definitions/89.html

## Strategic Recommendations

- Gate CI on Semgrep (including the Django, Python and secrets rulesets) ...
SectionContents
Header and overall riskAnalysis time, detected scanner, overall risk level and 0–100 score
Executive SummaryTwo to three sentences for leadership: overall risk, top threat, recommended focus
Findings at a GlanceCount per severity, plus raw versus de-duplicated finding counts
Immediate Actions RequiredThe top-priority fixes, referencing SPEC-NNN finding IDs
Attack ChainsFindings that combine into a higher-order risk, with the attack steps
Detailed FindingsEvery finding, sorted by severity: component, CVSS (when known), exploitability, description, remediation, and up to five references
Strategic RecommendationsLonger-term process, tooling or architecture improvements

JSON Report Structure

The JSON report is the full analysis as a single object. Field names and enum values are stable, so it is safe to build automation on. Example, trimmed to two findings:

{
  "executive_summary": "This SAST scan found six code-level weaknesses (no critical, three high, three medium), led by a string-concatenated SQL query in app/api/users.py ...",
  "overall_risk_score": 84,
  "risk_level": "HIGH",
  "scanner_type": "Semgrep",
  "scan_metadata": {
    "total_raw_findings": 6,
    "after_dedup": 6,
    "scan_timestamp": null
  },
  "findings_by_severity": {
    "CRITICAL": 0,
    "HIGH": 3,
    "MEDIUM": 3,
    "LOW": 0,
    "INFO": 0
  },
  "findings": [
    {
      "id": "SPEC-001",
      "severity": "HIGH",
      "title": "SQL injection via string concatenation in cursor.execute (users.py:47)",
      "description": "The `username` value is concatenated directly into a raw SQL string passed to `cursor.execute` ...",
      "affected_component": "app/api/users.py:47",
      "cvss_score": null,
      "exploitability": "Requires Access",
      "remediation": "Replace the concatenated query with a parameterized one ...",
      "references": [
        "https://cwe.mitre.org/data/definitions/89.html",
        "https://owasp.org/Top10/A03_2021-Injection/"
      ]
    },
    {
      "id": "SPEC-002",
      "severity": "HIGH",
      "title": "Hardcoded Stripe secret key committed in settings.py",
      "description": "`STRIPE_SECRET_KEY` is hardcoded in app/config/settings.py ...",
      "affected_component": "app/config/settings.py:42",
      "cvss_score": null,
      "exploitability": "Requires Access",
      "remediation": "1) Roll/revoke the key in the Stripe Dashboard now ...",
      "references": ["https://cwe.mitre.org/data/definitions/798.html"]
    }
  ],
  "attack_chains": [
    {
      "name": "SQL injection to mass account takeover",
      "description": "1) The attacker exploits the concatenated query in users.py (SPEC-001) ...",
      "finding_ids": ["SPEC-001", "SPEC-004"]
    }
  ],
  "immediate_actions": [
    "Fix SPEC-001: parameterize the query in app/api/users.py:47 ...",
    "Fix SPEC-002: roll the Stripe secret key in the Stripe Dashboard now ..."
  ],
  "strategic_recommendations": [
    "Gate CI on Semgrep (including the Django, Python and secrets rulesets) ..."
  ],
  "analyzed_at": "2026-11-13T02:16:07.981410Z"
}

Top-level fields

FieldTypeDescription
executive_summarystringTwo to three sentences for leadership
overall_risk_scoreinteger 0–100Worst realistic outcome if left unmitigated. 0 when the input contains no findings
risk_levelenumCRITICAL, HIGH, MEDIUM, or LOW
scanner_typestringDetected scanner, e.g. Trivy, Semgrep, Nessus, Mixed, Generic
scan_metadataobjecttotal_raw_findings (before de-duplication), after_dedup, scan_timestamp (ISO 8601 from the scan, or null)
findings_by_severityobjectCount per severity: CRITICAL, HIGH, MEDIUM, LOW, INFO
findingsarrayRanked findings, most severe first (see below)
attack_chainsarrayEach has name, description, and finding_ids (two or more SPEC-NNN IDs). Empty when no real chain exists
immediate_actionsarray of stringsTop-priority fixes
strategic_recommendationsarray of stringsLonger-term improvements
analyzed_atstringISO 8601 UTC time the report was produced

Finding fields

FieldTypeDescription
idstringSPEC-001, SPEC-002, … numbered within this report only
severityenumCRITICAL, HIGH, MEDIUM, LOW, or INFO (uppercase). SPECTRA’s contextual rating, which can differ from the scanner’s
titlestringShort, scannable title
descriptionstringWhat the issue is, why it matters, and what an attacker could do
affected_componentstringPackage and version, file path and line, service, or host
cvss_scorenumber or nullCVSS score when the scanner provides one; null otherwise (SPECTRA does not invent scores)
exploitabilityenumImmediate, Requires Access, Complex, or Theoretical
remediationstringThe specific fix: version to upgrade to, setting to change, or code pattern to apply
referencesarrayCVE IDs and URLs (advisories, CWE entries)

Token usage is not part of the report. Use --usage to print it to stderr.


Integrating JSON Output

Severity values are uppercase, so filter on "CRITICAL", not "critical".

Fail a CI job on critical findings:

spectra analyze trivy.json --format json --output reports/scan
jq -e '.findings_by_severity.CRITICAL == 0' reports/scan.json > /dev/null \
  || { echo "SPECTRA found critical findings"; exit 1; }

Jira (example):

# One ticket payload per critical or high finding
jq -c '.findings[] | select(.severity == "CRITICAL" or .severity == "HIGH")
       | {summary: "\(.id) \(.title)", component: .affected_component, description: .remediation}' \
  reports/scan.json | your-jira-ticket-script

Slack notification:

jq -n --arg text "SPECTRA: $(jq -r '"\(.risk_level) (\(.overall_risk_score)/100) — \(.executive_summary)"' reports/scan.json)" \
  '{text: $text}' | curl -sS -X POST -H 'Content-Type: application/json' -d @- "$SLACK_WEBHOOK"

Building the payload with jq keeps quotes and newlines in the summary from breaking the JSON.

SIEM ingest:

Ingest one document per element of findings[], and copy analyzed_at, scanner_type and risk_level onto each so they can be filtered. Don’t use findings[].id as a document ID: SPEC-NNN numbers restart in every report. To de-duplicate across scan runs, key on affected_component plus the CVE IDs in references. Both come from the scanner’s data. title and description are written by the model and vary between runs.


Next: CI/CD Integration →