batesian

README

Batesian

CLI for adversarial testing of A2A and MCP stacks. It drives concrete protocol traffic (OAuth audience/scope/DCR, push-notification callbacks, JWS card signatures, session and task boundaries, agent-card handling) and records outcomes as confirmed or indicator, with optional SARIF for CI.

Authorized use only. Run Batesian only against systems you own or targets covered by explicit written permission. The CLI issues attack-shaped traffic. Use outside that scope is your responsibility.

Secrets and TLS. Prefer BATESIAN_TOKEN or your secret manager over embedding long-lived bearer material in shared terminals, config repos, or CI logs. Use --skip-tls only when you must hit a host with intentionally broken TLS, such as a local lab on self-signed certificates.

Artifacts. JSON and SARIF can contain URLs, snippets, and evidence. Treat exports the same way you treat other sensitive scanner output in shared pipelines.

Custom rules. --rules-dir loads YAML from disk. Treat rule packs as untrusted input: they define what gets sent to the target.

What ships

Bundled rules: 14 A2A, 11 MCP (25 total). The set is deliberately narrow: every rule targets MCP/A2A-specific semantics (OAuth 2.1/DCR/audience binding and discovery-chain SSRF, JWS card signatures, agent-card canonicalization/cache/freshness, required-extension downgrade, push-notification SSRF and control-plane binding, task IDOR, role injection, version-downgrade bypass, SEP-2243 header/body routing, SSE resumption replay, cross-tenant isolation, session/context fixation, delegation chain-of-custody, credential leakage into responses), not generic web hygiene that nuclei/ZAP already cover. Each rule maps to CWE references and remediation text in the catalogs:

• A2A rules (14)
• MCP rules (11)

Findings record a confidence: confirmed (the attack demonstrably succeeded) or indicator (a suspicious posture that needs manual verification). Overlapping findings from rules in the same vulnerability class are coalesced by default (disable with --no-coalesce). scan --output json writes machine-readable JSON to stdout (status text goes to stderr), so batesian scan --output json | jq works.

Quickstart

go install github.com/calbebop/batesian/cmd/batesian@latest

batesian probe --target https://agent.example.com --protocol a2a

batesian scan --target https://agent.example.com --output sarif > results.sarif

batesian scan --target https://agent.example.com --rule-ids a2a-push-ssrf-001,mcp-resources-unauth-001

batesian scan --target https://mcp.example.com --token "$TOKEN"

batesian scan --target https://mcp.example.com \
  --token-url https://auth.example.com/oauth/token \
  --client-id my-client \
  --client-secret "$CLIENT_SECRET" \
  --oauth-scopes mcp:read,mcp:write

batesian scan --target https://mcp.example.com \
  --auth-url https://auth.example.com/authorize \
  --token-url https://auth.example.com/oauth/token \
  --client-id my-client \
  --oauth-scopes mcp:read

batesian scan --target https://agent.example.com \
  --principal name=tenant-a,token="$TOKEN_A",tenant=A \
  --principal name=tenant-b,token="$TOKEN_B",tenant=B

batesian init

probe is reconnaissance (table or JSON). It does not emit SARIF. For flags, filters, config files, OAuth, and extra rule paths: batesian scan --help.

Rule packs

Rules are YAML. New checks can ship without recompiling the binary. Authoring, schema, and review expectations are in CONTRIBUTING.md.

Build and test

make build
make test

Or: go build -o bin/batesian ./cmd/batesian and go test -race ./....

Contributing

Rules and code are welcome under Apache 2.0. See CONTRIBUTING.md. Vulnerable fixtures and port layout for tests: testdata/README.md.

References

• A2A Protocol Specification
• MCP Authorization Specification
• MCP Security Best Practices
• Unit 42: Agent Session Smuggling in A2A Systems
• OWASP GenAI Security Project

License

Apache 2.0. See LICENSE.

Documentation

Overview

Package batesian provides the embedded built-in attack rules. The go:embed directive lives here (at the repo root) so that the rules/ directory remains at the top level of the repository for easy contributor discovery and editing, while still being compiled into the binary.

Index

• func RulesFS() fs.FS

Functions

func RulesFS

func RulesFS() fs.FS

RulesFS returns the embedded built-in rules as an fs.FS rooted at "rules/". Pass this to rules.LoadFS to load all built-in attack rules.