Content
# RedTeam ML API MCP
Professional AI/ML API penetration testing and red-team simulation over MCP.
RedTeam ML API MCP is a defensive red-team simulator for ML and LLM APIs.
It exposes MCP tools and a CLI that let a security team run controlled test packs against an authorized AI/ML API endpoint, score the responses, generate evidence, and align results to SOC 2, ISO 27001, and GDPR control areas.
## Mindset Shift
This project is designed as an **adversarial validation plane** for AI systems.
The mindset shift is:
- From prompt lists to measurable security controls.
- From one-time red-team demos to continuous adversarial regression.
- From model safety only to full AI system safety: model, prompt, RAG, tools, identity, UI, and deployment.
- From guardrails as a checkbox to guardrails as evidence-backed controls.
- From pass/fail reports to release decisions with owners, evidence, and remediation.
For AWS-facing work, position it as:
**RedTeam ML API MCP validates whether Bedrock Guardrails, application policies, RAG boundaries, and agent tool controls are working before release.**
## AI API Pentest Mode
The red-team value is the pentest workflow:
1. Define authorized scope and rules of engagement.
2. Perform safe endpoint recon without infrastructure exploitation.
3. Run adversarial AI test campaigns.
4. Capture evidence for each case.
5. Calculate bypass rate by category.
6. Map failures to guardrail and architecture controls.
7. Align results to SOC 2, ISO 27001, and GDPR control areas.
8. Produce JSON and HTML artifacts for security review.
This is designed for authorized AI/ML API penetration testing. It does not perform credential attacks, destructive actions, third-party scanning, or infrastructure exploitation.
## Low-Impact Safety
The runner is built to avoid unnecessary pressure on target systems:
- Default delay between test cases.
- Per-request timeout.
- Optional max-case limit.
- Dry-run mode that validates scope without sending prompts.
- Explicit `--authorized` gate for pentest mode.
Example low-impact run:
```bash
redteam-ml-api pentest \
--target-url http://127.0.0.1:8765/chat \
--pack aws_2026_professional \
--authorized \
--delay-seconds 1.0 \
--max-cases 5
```
## Core Idea
Many ML APIs are deployed with weak safety, privacy, or operational controls. This project tests those controls before production by simulating realistic but safe adversarial requests.
The simulator focuses on:
- Prompt-injection resilience.
- Sensitive data leakage.
- Unsafe model behavior.
- Excessive confidence or hallucinated policy claims.
- Weak API contract behavior.
- Regression testing between model versions.
## Infrastructure Diagram
```mermaid
flowchart LR
Operator["Security / MLOps Operator"] --> Client["MCP Client\n(Codex, Claude, Cursor, etc.)"]
Client --> Server["RedTeam ML API MCP Server\nstdio JSON-RPC"]
Server --> Packs["Attack Packs\nJSON test cases"]
Server --> Runner["Test Runner\nrate limits + request templates"]
Runner --> Target["Authorized ML API\n/score, /chat, /predict"]
Target --> Runner
Runner --> Evaluator["Response Evaluator\nleakage + refusal + policy checks"]
Evaluator --> Store["Local Evidence\nJSON reports"]
Store --> Client
Client --> Report["Risk Summary + Remediation Plan"]
```
## Workflow
```mermaid
sequenceDiagram
participant U as Operator
participant C as MCP Client
participant M as RedTeam MCP Server
participant A as Attack Pack
participant T as Target ML API
participant E as Evaluator
U->>C: Run red-team pack against staging API
C->>M: tools/call run_red_team
M->>A: Load prompt-injection / leakage cases
loop Each test case
M->>T: Send authorized HTTP request
T-->>M: Return model/API response
M->>E: Score response
end
E-->>M: Findings + risk score
M-->>C: Structured report
C-->>U: Summary and fixes
```
## MCP Tools
### `list_attack_packs`
Lists available local test packs.
### `run_red_team`
Runs an attack pack against an authorized target.
Input:
```json
{
"target_url": "http://localhost:8000/chat",
"pack": "baseline_safe",
"method": "POST",
"timeout_seconds": 10
}
```
### `evaluate_text`
Scores a single response for risk signals.
Input:
```json
{
"text": "model response here"
}
```
### `generate_report`
Creates a compact remediation report from a previous run result.
### `generate_operating_model`
Creates a strategic operating-model brief for security teams, red teams, AI architects, platform teams, and executive sponsors.
It maps red-team categories to guardrail controls, architecture controls, owners, and release decisions.
### `run_ai_api_pentest`
Runs an authorized AI/ML API pentest workflow with scope, recon, campaign execution, evidence, metrics, release decision, and saved report artifacts.
## Quick Start
```bash
cd "/home/local-renad/renad-repo/RedTeam-ML-PenTest-MCP"
python3 -m venv .venv
. .venv/bin/activate
pip install -e ".[dev]"
python -m pytest
```
Run the demo API:
```bash
scripts/start_mock_api.sh
```
Open the browser health check:
```text
http://127.0.0.1:8765/
```
Try a sample browser request:
```text
http://127.0.0.1:8765/chat?input=hello
```
Stop the demo API when finished:
```bash
scripts/stop_mock_api.sh
```
Run the simulator in another terminal:
```bash
redteam-ml-api run --target-url http://127.0.0.1:8765/chat --pack baseline_safe
```
Run the professional 2026 AWS-facing pack:
```bash
redteam-ml-api run --target-url http://127.0.0.1:8765/chat --pack aws_2026_professional --report
```
Generate the mindset-shift operating model:
```bash
redteam-ml-api brief --target-url http://127.0.0.1:8765/chat --pack aws_2026_professional
```
Run a pentest engagement:
```bash
redteam-ml-api pentest \
--target-url http://127.0.0.1:8765/chat \
--pack aws_2026_professional \
--tester "Red Team" \
--environment "staging" \
--authorized
```
Run from a reusable config file:
```bash
redteam-ml-api pentest --config examples/pentest_scope.json
```
Authenticated API example:
```bash
redteam-ml-api pentest \
--target-url https://api.example.com/chat \
--authorized \
--bearer-token "$API_TOKEN" \
--header "X-Environment: staging" \
--input-field message \
--delay-seconds 1.0
```
Reports are saved under:
```text
reports/
```
Or run the full demo:
```bash
scripts/demo_pentest.sh
```
More details:
- [Quickstart](docs/QUICKSTART.md)
- [Control Mapping](docs/CONTROL_MAPPING.md)
- [Example Scope](examples/pentest_scope.json)
Start the MCP server:
```bash
redteam-ml-api-mcp
```
## MCP Client Config
```json
{
"mcpServers": {
"redteam-ml-api": {
"command": "python",
"args": ["-m", "redteam_ml_api_mcp.server"],
"cwd": "/Users/renad-local/renad-repo/RedTeam-ML-PenTest-MCP"
}
}
}
```
## Safety Boundary
This project is for authorized defensive testing only. It does not exploit infrastructure, bypass authentication, scan third-party systems, or generate malware. Attack packs are plain JSON so teams can review exactly what is being sent.
