mirror of
https://github.com/KeygraphHQ/shannon.git
synced 2026-08-11 05:50:21 +02:00
ezl-keygraphandGitHub
a1675f8390
* feat(cli): support any Pi provider via generic SHANNON_AI_API_KEY * docs(cli): point users to pi.dev/models for provider and model ids * docs: document generic provider path and pi.dev catalogue
177 lines
8.2 KiB
Markdown
177 lines
8.2 KiB
Markdown
# AI Providers
|
|
|
|
One model runs the entire scan — pre-recon, recon, vulnerability analysis, exploitation, and reporting. A single setting names both the provider and the model:
|
|
|
|
```bash
|
|
export SHANNON_AI_MODEL=<provider>:<model-id>
|
|
```
|
|
|
|
The provider half decides where the request goes, which credential is used, and which API dialect is spoken. You never configure those separately.
|
|
|
|
## Supported providers
|
|
|
|
| Provider | Value | Credential |
|
|
| --- | --- | --- |
|
|
| Anthropic | `anthropic` | `SHANNON_AI_API_KEY` (or `CLAUDE_CODE_OAUTH_TOKEN`) |
|
|
| OpenAI | `openai` | `SHANNON_AI_API_KEY` |
|
|
| xAI | `xai` | `SHANNON_AI_API_KEY` |
|
|
| AWS Bedrock | `amazon-bedrock` | `AWS_REGION` and `AWS_BEARER_TOKEN_BEDROCK` |
|
|
|
|
`SHANNON_AI_API_KEY` holds the key for whichever provider `SHANNON_AI_MODEL` names. Bedrock is the exception — it authenticates through its `AWS_` variables only. If `SHANNON_AI_MODEL` is unset, Shannon uses `anthropic:claude-sonnet-4-6`.
|
|
|
|
Anthropic, OpenAI, and xAI also accept their native variables (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `XAI_API_KEY`); if one of those is set, it is used instead of `SHANNON_AI_API_KEY`.
|
|
|
|
Shannon forwards only the selected provider's credential into the scan container. Keys for other providers stay on your machine.
|
|
|
|
### Any other provider
|
|
|
|
Shannon accepts any provider and model present in the Pi harness catalogue. Browse them at [pi.dev/models](https://pi.dev/models). These are technically supported but not recommended. Claude models are best-supported (see the note below).
|
|
|
|
```bash
|
|
export SHANNON_AI_API_KEY=your-api-key # the provider's API key
|
|
export SHANNON_AI_MODEL=openrouter:moonshotai/kimi-k3 # <provider>:<model-id>
|
|
```
|
|
|
|
This path covers providers whose credential is a single API key. Providers that need more than that are not currently supported.
|
|
|
|
`npx @keygraph/shannon setup` exposes this as the **Other provider** option.
|
|
|
|
> [!IMPORTANT]
|
|
> Claude models are the best-supported option. Shannon's evaluations, internal testing, and agent harness are tuned for Claude. Other models are permitted and validated against the harness catalogue, but may not follow Shannon's instructions or tool-use constraints as reliably. Use them at your own risk.
|
|
|
|
## Cyber safeguards (do this before your first scan)
|
|
|
|
Anthropic and OpenAI both apply real-time safeguards to cyber-security workloads. Shannon is exactly such a workload. If a safeguard engages mid-run, the model can refuse, and the scan fails partway through rather than at the start.
|
|
|
|
Review each vendor's guidance and complete the verification or enrollment they ask of legitimate security testers before running Shannon:
|
|
|
|
- Anthropic - [Real-time cyber safeguards on Claude Opus and Sonnet](https://support.claude.com/en/articles/14604842-real-time-cyber-safeguards-on-claude-opus-and-sonnet)
|
|
- OpenAI - [Cyber](https://chatgpt.com/cyber)
|
|
|
|
This applies to the Anthropic and OpenAI providers, including when either is reached through a gateway. Bedrock serves Claude models and is subject to Anthropic's safeguards as well.
|
|
|
|
## Suggested models
|
|
|
|
These are the models `npx @keygraph/shannon setup` offers, best-first. They are suggestions: the wizard also takes a typed model ID, and `SHANNON_AI_MODEL` accepts any model in the provider's catalogue.
|
|
|
|
| Provider | Suggested model IDs |
|
|
| --- | --- |
|
|
| `anthropic` | `claude-sonnet-4-6`, `claude-opus-4-8`, `claude-opus-4-7`, `claude-haiku-4-5-20251001` |
|
|
| `openai` | `gpt-5.6-sol`, `gpt-5.5`, `gpt-5.4` |
|
|
| `xai` | `grok-4.5` |
|
|
| `amazon-bedrock` | `us.anthropic.claude-sonnet-4-6`, `us.anthropic.claude-opus-4-8`, `us.anthropic.claude-opus-4-7` |
|
|
|
|
Bedrock IDs are region-prefixed and must be enabled in your account, so the ID that works for you may differ from the one listed here.
|
|
|
|
## Switching provider
|
|
|
|
The pattern is learned once: export the provider's key, name the model. Two lines change, nothing else.
|
|
|
|
Anthropic (default):
|
|
|
|
```bash
|
|
export SHANNON_AI_API_KEY=sk-ant-...
|
|
export SHANNON_AI_MODEL=anthropic:claude-sonnet-4-6
|
|
```
|
|
|
|
OpenAI:
|
|
|
|
```bash
|
|
export SHANNON_AI_API_KEY=sk-...
|
|
export SHANNON_AI_MODEL=openai:gpt-5.6-sol
|
|
```
|
|
|
|
xAI:
|
|
|
|
```bash
|
|
export SHANNON_AI_API_KEY=xai-...
|
|
export SHANNON_AI_MODEL=xai:grok-4.5
|
|
```
|
|
|
|
Source-build mode reads the same variables from a `.env` file.
|
|
|
|
## AWS Bedrock
|
|
|
|
Run `npx @keygraph/shannon setup` and select **AWS Bedrock**, or export directly:
|
|
|
|
```bash
|
|
export AWS_REGION=us-east-1
|
|
export AWS_BEARER_TOKEN_BEDROCK=your-bearer-token
|
|
export SHANNON_AI_MODEL=amazon-bedrock:us.anthropic.claude-opus-4-8
|
|
```
|
|
|
|
Bedrock uses bearer-token authentication only. IAM access keys, session tokens, assumed roles, and instance profiles are not supported. The model must be enabled in your region.
|
|
|
|
## Custom base URL
|
|
|
|
To route model traffic through your own infrastructure — a corporate proxy, an LLM gateway such as LiteLLM, or a regional endpoint — set a base URL alongside your normal model selection. The provider half of `SHANNON_AI_MODEL` decides which key is sent and which API Shannon speaks, so pick the one your gateway serves:
|
|
|
|
| Gateway serves | Model prefix | API key |
|
|
| --- | --- | --- |
|
|
| Anthropic Messages | `anthropic:` | `SHANNON_AI_API_KEY` |
|
|
| OpenAI Chat Completions | `openai:` | `SHANNON_AI_API_KEY` |
|
|
| OpenAI Responses | `openai:` + `SHANNON_AI_OPENAI_FORMAT=responses` | `SHANNON_AI_API_KEY` |
|
|
|
|
The model ID is whatever name your gateway serves it under; it does not have to exist in Shannon's catalogue.
|
|
|
|
Anthropic Messages:
|
|
|
|
```bash
|
|
export SHANNON_AI_API_KEY=sk-ant-...
|
|
export SHANNON_AI_MODEL=anthropic:claude-sonnet-4-6
|
|
export SHANNON_AI_BASE_URL=https://llm-gateway.example.com
|
|
```
|
|
|
|
OpenAI Chat Completions:
|
|
|
|
```bash
|
|
export SHANNON_AI_API_KEY=sk-...
|
|
export SHANNON_AI_MODEL=openai:gpt-5.6-sol
|
|
export SHANNON_AI_BASE_URL=https://llm-gateway.example.com/v1
|
|
```
|
|
|
|
`SHANNON_AI_MODEL` is always `<provider>:<model-id>`, gateway or not.
|
|
|
|
OpenAI is the one provider serving two APIs, so a gateway run picks one:
|
|
|
|
```bash
|
|
export SHANNON_AI_OPENAI_FORMAT=responses # default: chat-completions
|
|
```
|
|
|
|
Chat Completions is the default because that is what most gateway software exposes. Set `responses` for a gateway that passes the Responses API through — it preserves reasoning state between turns, which Chat Completions cannot. `openai:gpt-5` with no base URL always calls OpenAI's Responses API directly.
|
|
|
|
The variable is rejected in preflight where it cannot take effect: with a non-`openai` model, since Anthropic, xAI, and Bedrock each serve one API, and with no `SHANNON_AI_BASE_URL`, since a direct OpenAI run is always Responses.
|
|
|
|
`npx @keygraph/shannon setup` covers this under **Custom Base URL**, which asks which API your gateway serves and configures the matching provider for you.
|
|
|
|
## Validation
|
|
|
|
Checks run before a scan starts, so mistakes fail immediately rather than partway through a run:
|
|
|
|
- **Provider and model ID** — validated against the Pi harness catalogue. An unknown provider or model ID fails preflight with a pointer to [pi.dev/models](https://pi.dev/models). A custom base URL exempts the model ID, since a gateway may serve its own names.
|
|
- **Credential presence** — always validated for the selected provider.
|
|
- **Credential validity** — one minimal request against the model the scan will use, so a rejected key, an exhausted quota, or a model the account cannot reach fails before any agent runs. Bedrock included: its bearer token and region go through the same probe.
|
|
|
|
## Migrating from the three-tier configuration
|
|
|
|
Earlier versions took three model variables. They no longer do anything — replace them with `SHANNON_AI_MODEL`.
|
|
|
|
| Before | Now |
|
|
| --- | --- |
|
|
| `ANTHROPIC_SMALL_MODEL`, `ANTHROPIC_MEDIUM_MODEL`, `ANTHROPIC_LARGE_MODEL` | a single `SHANNON_AI_MODEL` |
|
|
| `CLAUDE_CODE_USE_BEDROCK=1` plus three Bedrock model IDs | `SHANNON_AI_MODEL=amazon-bedrock:<model-id>` |
|
|
| `ANTHROPIC_BASE_URL` + `ANTHROPIC_AUTH_TOKEN` selected a provider | `SHANNON_AI_BASE_URL` overrides the endpoint; `SHANNON_AI_MODEL` selects the provider |
|
|
|
|
In `~/.shannon/config.toml`, the `[models]` section and `bedrock.use` are gone, each provider has its own section, and the model lives at `core.model`:
|
|
|
|
```toml
|
|
[core]
|
|
model = "anthropic:claude-sonnet-4-6"
|
|
# base_url = "https://llm-gateway.example.com"
|
|
|
|
[anthropic]
|
|
api_key = "your-api-key"
|
|
```
|
|
|
|
Re-run `npx @keygraph/shannon setup` to regenerate the file.
|