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. To review the traffic a scan would generate before authorizing it, run scan --dry-run: it records and prints every request and sends nothing.

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: 17 A2A, 18 MCP (35 total). The set is deliberately narrow - every rule targets MCP/A2A-specific semantics, not generic web hygiene that nuclei/ZAP already cover. Each rule maps to CWE references and remediation text in the catalogs:

• A2A rules (17)
• MCP rules (18)

Rules are validated against third-party reference implementations, not only against the bundled fixtures. Validation results records what fires, what correctly stays silent on a server with no authentication at all, and the scanner defects that exercise has found.

Coverage spans:

• OAuth & token validation - OAuth 2.1 / DCR scope escalation, audience binding, token replay, version-downgrade bypass, forged-token acceptance, redirect_uri confused deputy
• Agent-card trust (A2A) - JWS signatures, canonicalization, cache/freshness, required-extension downgrade, host-header injection, unauthenticated extended card, declared-but-unenforced auth
• Request & task integrity - task IDOR, agent-role injection, artifact tampering, SEP-2243 header/body routing, SSE resumption replay
• Multi-party isolation - cross-tenant isolation, session/context fixation, delegation chain-of-custody, cross-principal task cancellation, cross-context MCP task and result access
• SSRF & secret leakage - push-notification SSRF, push control-plane binding, OAuth discovery/metadata SSRF, credential leakage into responses
• Unauthenticated & cross-origin access - exposed MCP tools, resources, prompt templates, completion suggestions, and log-level control, Streamable HTTP Origin validation (DNS rebinding)

Install

Pre-built, signed binaries for Linux, macOS, and Windows (amd64/arm64) are attached to every release:

# Download the archive for your platform from the Releases page, then:
tar xzf batesian_<version>_linux_x86_64.tar.gz
./batesian --help

Or build from source with Go 1.25+:

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

Quickstart

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 scan --target https://agent.example.com --dry-run

batesian init

probe is reconnaissance (table or JSON). It does not emit SARIF. batesian init writes an annotated batesian.yaml to the current directory (it will not overwrite an existing one) so targets, tokens, and rule selections can live in version-controlled config. For flags, filters, config files, OAuth, and extra rule paths: batesian scan --help.

CI integration

scan --output sarif writes SARIF 2.1.0 to stdout. Upload it to the GitHub Security tab with the standard action:

name: batesian
on: [push, pull_request]
jobs:
  scan:
    runs-on: ubuntu-latest
    permissions:
      security-events: write   # upload SARIF to the Security tab
    steps:
      - uses: actions/setup-go@v5
        with:
          go-version: '1.25'
      - run: go install github.com/calbebop/batesian/cmd/batesian@latest
      - run: batesian scan --target https://agent.example.com --output sarif > results.sarif
      - uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: results.sarif

Findings surface as code-scanning alerts. scan exits non-zero only on an operational error, not on findings, so gating is handled by the Security tab (or by parsing --output json).

Rule packs

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

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.