Metadata-Version: 2.4
Name: so-what-cli
Version: 0.1.0
Summary: Rewrite a threat report for a chosen audience: SOC, CISO, exec, board.
Author: Paul Goodwin
License: MIT
Project-URL: Homepage, https://github.com/SkeinLLC/so-what-cli
Project-URL: Issues, https://github.com/SkeinLLC/so-what-cli/issues
Keywords: cti,threat-intelligence,icd-203,security,writing,llm
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Classifier: Topic :: Text Processing
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pyyaml>=6.0
Requires-Dist: httpx>=0.27
Requires-Dist: rich>=13.7
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.30; extra == "anthropic"
Provides-Extra: openai
Requires-Dist: openai>=1.30; extra == "openai"
Provides-Extra: docx
Requires-Dist: python-docx>=1.1; extra == "docx"
Provides-Extra: pdf
Requires-Dist: pypandoc>=1.13; extra == "pdf"
Provides-Extra: all
Requires-Dist: anthropic>=0.30; extra == "all"
Requires-Dist: openai>=1.30; extra == "all"
Requires-Dist: python-docx>=1.1; extra == "all"
Requires-Dist: pypandoc>=1.13; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pytest-mock>=3.12; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Dynamic: license-file

# 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

```bash
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:

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

## Use it

```bash
# 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

```bash
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.
