so-what-cli

Rewrite a threat report for a chosen audience: SOC, CISO, non-security exec, or board.

The same intel needs different products for different readers. SOC wants detections and IOCs. The CISO wants decision-grade business framing. The exec wants plain English. The board wants governance language. Most teams write one product and send it to all four, which is why nobody finds it useful.

This CLI does the translation. Reads markdown or text from a file (or stdin), runs it through a prompt tuned for the target audience, and writes back markdown, docx, or PDF. Pluggable LLM backend so it works with whatever you've got: Anthropic, OpenAI, or local Ollama.

Install

pip install so-what-cli                 # core
pip install 'so-what-cli[anthropic]'    # Claude backend
pip install 'so-what-cli[openai]'       # GPT backend
pip install 'so-what-cli[docx]'         # docx output
pip install 'so-what-cli[pdf]'          # pdf output (needs pandoc on PATH)
pip install 'so-what-cli[all]'          # everything

Set one of the API keys, or run a local Ollama:

export ANTHROPIC_API_KEY=sk-ant-...
# or
export OPENAI_API_KEY=sk-...
# or, for local
ollama serve
ollama pull llama3.1:8b

Use it

# rewrite a vendor advisory for the CISO, tied to your asset profile
so-what advisory.md --audience ciso --asset-profile profile.yaml

# pipe a CISA KEV note through and get a SOC product
curl -s https://example.com/advisory.txt | so-what - --audience soc

# build a board pack one-pager as a docx
so-what advisory.md --audience board --format docx --output board.docx

# see what's in the prompt without spending tokens
so-what advisory.md --audience exec --asset-profile profile.yaml --dry-run

Flags worth knowing:

• --audience (required): soc, ciso, exec, board.
• --asset-profile: YAML file describing your org. See examples/asset-profile.yaml.
• --format: md (default), docx, pdf.
• --output: file path. Defaults to stdout for markdown.
• --backend: anthropic, openai, ollama. Defaults based on env vars present.
• --model: override the backend default.
• --dry-run: print the assembled system + user prompts. Don't call the model.
• --extra-context: free-text context (incident ref, prior assessment, anything).

Why the audiences are shaped the way they are

The prompts in src/so_what/audiences/ are opinionated. They follow:

• ICD-203 confidence language for assessments, plain hedging for facts. The IC's analytic standards are a useful baseline for any analyst writing under uncertainty.
• The cyclical arc from Heuer's tradecraft tradition: problem, impact in the reader's terms, mitigation. Compressed for executives, expanded for SOC.
• The banned-vocab list from voice-DNA. No vendor breathless adjectives. No filler that signals AI-written copy. The brand here is analyst-grade output.

If you don't like one of the audience prompts, edit the markdown. The prompts are the product.

Asset profile

The profile YAML grounds the rewrite in your org. Required keys are org_name and industry. The recommended fields (regions, regulators, key vendors, crown jewels, internet-facing tech, identity provider, EDR) let the model tie threats to the specific assets that matter. Without a profile the output is generic; with one, it stops being generic.

See examples/asset-profile.yaml for the full shape.

What's in the repo

so-what-cli/
  src/so_what/
    cli.py
    prompts.py        # audience prompt loading + user prompt assembly
    profiles.py       # YAML asset profile loader
    render.py         # md/docx/pdf output
    audiences/
      soc.md          # SOC / IR analyst voice + structure
      ciso.md         # decision-grade executive summary voice
      exec.md         # non-security exec, BLUF, business outcomes
      board.md        # board / audit committee, governance frame
    backends/
      anthropic_backend.py
      openai_backend.py
      ollama_backend.py
  tests/
    test_cli.py
    fixtures/
      sample-advisory.md
  examples/
    asset-profile.yaml

Testing

pip install 'so-what-cli[dev]'
pytest

The tests don't call any LLM. They check argparse, prompt loading, profile validation, and dry-run output assembly. Run them on every PR.

Status

Alpha. v0.1. Audience prompts validated against a synthetic sample advisory. Next: validate against 10 real public CVEs from the last 90 days and tune the prompts. PRs welcome on audience prompt quality, additional output formats, and additional backends.

License

MIT. See LICENSE.

Related

This is the OSS engine behind the hosted version at so-what.app. The hosted version adds a web UI, team accounts, saved asset profiles, and Slack delivery. The CLI is free and always will be.