Aginiti Red-Team Framework 🛡️🤖

Aginiti is an autonomous security-assessment and penetration-testing engine for enterprise agentic AI systems — chatbots, RAG assistants, tool-calling agents, and multi-agent fleets.

Rather than executing a static list of prompts and checking pass/fail, Aginiti builds an active Security State Graph (SSG) of the target, evaluates security controls, and plans multi-step exploits autonomously — the way a human red-teamer reasons, at machine speed.

Proven, not just architected: benchmarked head-to-head against fixed-order enumeration (~5x fewer requests to the same outcomes) and validated against NVIDIA's garak (findings agreed exactly on every comparable category) on real, production-realistic targets. 11 attack methodologies, grounded in 10+ published research papers, 1,925 tests. Full numbers: docs/BENCHMARKS.md.

---

🚀 Installation

Install the core library (for running standalone attacks and HTTP adapters):

pip install aginiti-redteam

Add [demo-target] for a local target agent to try Aginiti against, with no target of your own required:

pip install "aginiti-redteam[demo-target]"

Already have your own target agent and don't need the demo one? The plain pip install aginiti-redteam above is all you need — skip the extra.

---

⚙️ Configuration & Prerequisites

Aginiti campaigns use an LLM provider to evaluate vulnerability conditions, judge target responses, and calculate attacker utility.

Set up your API keys in your environment or a .env file:

# Attacker/Judge LLM keys (LiteLLM routes these automatically). Set any one --
# the CLI below auto-detects whichever is present and picks that provider's
# current default model.
GEMINI_API_KEY=your_gemini_api_key
OPENAI_API_KEY=your_openai_api_key
GROQ_API_KEY=your_groq_api_key
ANTHROPIC_API_KEY=your_anthropic_api_key
MISTRAL_API_KEY=your_mistral_api_key

---

⚡ CLI Quickstart (no code required)

Run a real assessment straight from your terminal:

# Start a local target agent to try Aginiti against (seeds itself, then serves on :8001)
aginiti-demo-target
#   Port 8001 already taken? Run it on another one instead:
aginiti-demo-target --port 8010
#   Vulnerable by default (--vanilla) -- add --hardened for a defended A/B comparison:
aginiti-demo-target --hardened

# In a second terminal: aginiti scan -- let it decide (try this first)
aginiti scan --target http://localhost:8001 --tier data_leakage --budget 15
aginiti scan --target http://localhost:8001 --tier unauthorized_actions --budget 15
aginiti scan --target http://localhost:8001 --tier discovery_recon --budget 10
aginiti scan --target http://localhost:8001 --tier full_assessment --budget 20

# ...or aginiti attack -- you decide, one technique at a time
aginiti attack spe --target http://localhost:8001
aginiti attack ikea --target http://localhost:8001 --topic "HR records" --queries 10
aginiti attack secret --target http://localhost:8001 --domain "HR records" --queries 10
aginiti attack mia --target http://localhost:8001 --dataset candidates.json

# Regenerate a Markdown report for a past run, without re-running anything
aginiti report --input results/<run>/findings.json

Every scan/attack run prints one authorized-use reminder, then auto-saves findings.json (the full structured result), aginiti_assessment_report.md (a human-readable, OWASP LLM Top 10–mapped Markdown report), and aginiti_assessment_report.html (the same report, styled for a browser) into their own fresh, timestamped subdirectory of ./results (--output-dir to redirect elsewhere), e.g. results/2026-09-23_154012/ — so a later run never overwrites an earlier one's results. The HTML report opens in your default browser automatically the moment the run finishes (--no-open-report to skip this) — no Markdown viewer needed, so it's easy to hand to a non-technical reader too. --tier accepts data_leakage | unauthorized_actions | discovery_recon | full_assessment; use --attack-category instead for one of 11 precise named groups (aginiti scan --list-attack-categories to see all of them). Every subcommand has its own --help; aginiti attack mia --dataset expects a JSON file shaped {"documents": [{"id", "text"}, ...], "non_member_reference_docs": [{"id", "text"}, ...]}.

Point --target at any real, HTTP-reachable agent you're authorized to test instead of the local demo target — nothing about the CLI requires it.

---

💻 Python API

Aginiti supports two modes of execution: Direct Mode (for full-scale standalone audits) and Adaptive Mode (for autonomous orchestrated campaigns).

1. Direct Mode (Standalone Auditing)

Use this mode to run a targeted, heavy search loop against an endpoint using one of our mathematical exfiltration/jailbreak algorithms.

Example: IKEA Data Reconstruction Attack

This attack attempts to reconstruct sensitive records (such as database entries) from the target agent's RAG system.

from aginiti.attacks.dra.ikea import IKEAAttack

# 1. Initialize the standalone attack
attack = IKEAAttack(
    target_url="http://localhost:8001",  # base URL only -- AgentEndpoint appends /chat itself
    llm_provider="gemini/gemini-3.5-flash",
    api_key="your_api_key"
)

# 2. Run the exfiltration audit
# topic: the target domain containing sensitive info
# max_queries: query budget to extract and verify data reconstruction
findings = attack.execute_black_box(topic="HR Payroll database", max_queries=20)

# 3. Analyze results
for finding in findings:
    if finding.confirmed:
        print(f" leaked content: {finding.leaked_content}")
        print(f"   Severity: {finding.severity} | Confidence: {finding.confidence}")

Other available standalone attacks include:

• SECRETAttack (aginiti.attacks.dra.secret): Iterative adversarial jailbreak suffix optimization.
• InterrogationAttack (aginiti.attacks.mia.interrogation): Membership Inference Attack to check if specific PII records were used to train or ground the target agent.
• SPELLMAttack (aginiti.attacks.spe.spe_llm): System Prompt Extraction audit.

---

2. Adaptive Mode (Autonomous Campaigns)

Use this mode to run the Aginiti Campaign Engine. The planner evaluates the target's security state graph and selects the optimal sequence of reconnaissance and exploitation operators.

Example: Setting up a Campaign

from aginiti.core.campaign import run_campaign
from aginiti.core.scenarios import multi_path_mission
from aginiti.operators.definitions import build_library
from aginiti.adapters.http_agent_adapter import HTTPAgentAdapter
from aginiti.connectors.endpoint import AgentEndpoint

# 1. Establish a persistent session to the target agent
endpoint = AgentEndpoint(base_url="http://localhost:8001")
agent_adapter = HTTPAgentAdapter(endpoint)

# 2. Configure the audit mission and build the operators
mission = multi_path_mission()
library = build_library()

# 3. Run the campaign loop
result = run_campaign(
    mission=mission,
    library=library,
    agent=agent_adapter,
    max_steps=25
)

# 4. Review the outcome
print(f"Campaign Outcome: {result.outcome}")  # SUCCESS | BUDGET_EXHAUSTED
print(f"Steps executed: {result.steps_executed}")
print(f"Total prompt budget spent: {result.prompts_used}")

---

🎯 Fine-Tuning the Audit Scope

You can filter the operator library to restrict the campaign to specific types of attacks.

Filtering by Security Tier

Tiers represent broad categories of security posture. You can filter the operator library in Python before launching the campaign:

from aginiti.operators.data_exposure import data_exposure_operators
from aginiti.operators.deep_attack_operators import deep_attack_operators
from aginiti.operators.library import OperatorLibrary

# Load all core operators
all_operators = [*data_exposure_operators(), *deep_attack_operators()]

# Example: Filter to only include Data Leakage operators (IKEA, SECRET, MIA, SPE)
data_leakage_operators = [
    op for op in all_operators 
    if op.effects_success and op.effects_success[0].owasp_llm_category in {
        "LLM02_SENSITIVE_INFORMATION_DISCLOSURE", "LLM07_SYSTEM_PROMPT_LEAKAGE"
    }
]

library = OperatorLibrary(data_leakage_operators)

Filtering by Attack Category

You can also filter the library by one of the 11 specific attack methodologies using .by_category():

# Allowed Categories: 
# "direct_prompt_attack", "encoding_attack", "rag_poisoning", 
# "indirect_injection", "tool_discovery", "tool_manipulation", 
# "markdown_network_exfiltration", "multi_step_chain", 
# "decoy", "known_defended", "low_value_reconnaissance"

library = OperatorLibrary(all_operators).by_category("multi_step_chain", "tool_discovery")

---

🛠️ Troubleshooting Windows Installation

On certain Windows machines, compiling vector databases locally using chromadb can trigger an onnxruntime or numpy DLL loading exception.

If you encounter a DLL load failed error, resolve it by installing these compatible binary versions:

pip install onnxruntime==1.17.0 numpy==1.26.4

Alternatively, bypass local ONNX computation completely by setting up cloud-based embeddings (e.g. embed_model="openai/text-embedding-3-small").

---

📊 Result Analysis & Evidence Extraction

After a campaign finishes, you can extract the final security graph claims to generate compliance or vulnerability reports:

# Print verified vulnerabilities discovered during the campaign
for claim in result.ssg.claims:
    print(f"Vulnerability: {claim.key} -> Status: {claim.status.value} (Confidence: {claim.confidence.value})")

---

🔗 Links & Resources

• GitHub Repository: For local developer setups, starting Docker target containers, or contributing, visit Aginiti Red-Team GitHub.
• Full Usage Guide: docs/USAGE.md — every attack's parameters and query budget, target authentication, where results/cache files land, and a gotchas/FAQ list.
• Hands-on Tutorial: docs/TUTORIAL.md — a copy-paste walkthrough of the full CLI and Python API, start to finish.
• Detailed Documentation: Refer to the docs/ folder in the repository for detailed papers on the Aginiti planning model, evidence classification, and mitigation guides.
• Contributors: Muhammad Hammad Irfan, Omer Bin Dawood
• License: MIT