Agentshield

Red-team your tool-using LLM agent in CI: run it against prompt-injection and exfiltration scenarios in a sandbox, score every tool call against a policy, and fail the pull request when it leaks.

30-second quickstart

git clone https://github.com/adityasharma1307/agentshield.git && cd agentshield
python -m venv .venv && . .venv/bin/activate      # Windows: .venv\Scripts\activate
pip install .

# A careful agent passes: exit 0
python -m agentshield run --agent examples.careful_agent.agent:agent \
  --suite src/agentshield/scenarios/suites --policy src/agentshield/scoring/default_policy.yaml

# A leaky agent follows planted instructions and leaks a canary: exit 1, failing rules listed
python -m agentshield run --agent examples.leaky_agent.agent:agent \
  --suite src/agentshield/scenarios/suites --policy src/agentshield/scoring/default_policy.yaml

Run it with python -m from the checkout so the examples package is importable. To gate your own agent, point --agent at your_module:your_agent, or use the GitHub Action:

- uses: adityasharma1307/agentshield@main
  with:
    agent: your_package.agent:agent
    suites: src/agentshield/scenarios/suites
    policy: src/agentshield/scoring/default_policy.yaml
    fail_on: high

What it does

• Adapters. One interface, AgentUnderTest.step, returns the agent's next tool calls or its final answer, and the agent never executes tools itself. Adapters cover HTTP, the OpenAI SDK, and LangGraph.
• Sandbox. Every tool call goes through a mock ToolRegistry (search, read_file, send_email, http_get, db_query), each with a deterministic trap variant. Step and time limits apply.
• Scenarios. 22 adversarial scenarios cover injection, exfiltration, scope creep, policy violation, and tool jailbreak. agentshield scenarios lists them.
• Scoring. A declarative YAML policy is applied to the ordered trace. The default policy is tagged for the EU AI Act, the NIST AI RMF, India's DPDP Act, and UAE and DIFC data law.
• Reports and gating. Reports are signed and checked with agentshield verify. The Docker GitHub Action fails a pull request at or above a chosen severity. An optional FastAPI service and React dashboard are included.

CI replays recorded fixtures and never calls a model provider. Local example-agent results are in RESULTS.md.

Threat model in brief

The agent under test, and everything a scenario feeds it, are treated as hostile. Agentshield measures whether the agent stays inside the policy, and it keeps scenario side effects off the host:

• Holds today: tools are mocks only, tool output is deterministic, step and wall-clock limits apply, and the trace is complete, including rejected calls. Spans carry argument hashes, not raw arguments.
• Network containment needs subprocess mode with firejail installed. In the default inprocess mode, a handler that opens its own socket is not stopped. Each run reports which boundary it actually had.
• Out of scope: the model provider (prompts leave the machine), adapter code the operator chose to install, and binding a qknot signature to a person.

Read the full threat model before pointing a live agent at this tree. To report a vulnerability, see SECURITY.md.

Install

Python 3.11 or newer. From PyPI, the distribution is named agsh. The import package and the command are both agentshield:

pip install agsh
agentshield --version

Extras use the same name, for example pip install "agsh[openai]". agentshield on PyPI is an unrelated project.

To work on the code, install from a checkout of this repository:

python -m venv .venv

On Windows, activate with .venv\Scripts\activate. On macOS and Linux, activate with source .venv/bin/activate.

python -m pip install -e ".[dev,docs]"
agentshield --version

The OpenAI, LangGraph, OpenTelemetry, and service clients are optional: agsh[openai], agsh[langgraph], agsh[otel], and agsh[service] (or .[openai] and so on from a checkout). The core install does not import them.

Documentation

• Quickstart
• Adapters
• Sandbox
• Tracing
• Service
• Dashboard
• Threat model
• Writing scenarios
• Policy reference
• Roadmap

mkdocs build --strict builds the site after the docs extra is installed.

Development

ruff check .
ruff format --check .
mypy
pytest

Contributor workflow, versioning, and the changelog rule are in CONTRIBUTING.md.

License

MIT