AISecurityLab/hackagent

HackAgent – AI‑Agent Security Red‑Team Toolkit

What it is – HackAgent is a Python SDK and command‑line tool that lets you probe the safety of AI agents (chat‑bots, autonomous assistants, etc.). It bundles a library of known attack techniques (prompt injection, jailbreaks, goal hijacking, tool misuse) and a small framework for generating adversarial prompts, running them against a target agent, and judging whether the agent’s safeguards were bypassed.

Why it matters – As LLM‑driven agents become more autonomous, traditional software‑testing tools miss the kinds of attacks that manipulate the model’s reasoning or exploit its tool‑use abilities. HackAgent provides a ready‑made, research‑backed pipeline so security researchers and AI‑safety engineers can evaluate those risks without building their own attack harnesses.

---

Core components

Component	Role
Attack Engine	Executes a catalog of attacks (AdvPrefix, AutoDAN‑Turbo, PAIR, TAP, FlipAttack, BoN, h4rm3l, CipherChat, PAP, Static Template).
Generator	An LLM that crafts adversarial prompts for a given target.
Judge	An LLM that decides whether an attack succeeded (i.e., the target violated its safety policy).
Target Agent	The AI agent you want to test – any agent built with supported SDKs.
Datasets	Built‑in benchmark sets and the ability to load custom JSON, HuggingFace, or URL‑based datasets.

---

Supported AI frameworks

• Google ADK
• OpenAI SDK
• LiteLLM
• LangChain

Any agent built on one of these can be plugged into the pipeline with minimal configuration.

---

Installing & running

# Typical Python install
python3 -m venv .venv && source .venv/bin/activate
pip install hackagent

No API key is needed for local use.

A self‑contained binary is also published for Linux, macOS, and Windows, so you can run hackagent without a Python runtime. (The only external requirement is Playwright’s browsers for the hackagent web command.)

---

Typical workflow (CLI example)

# 1. Choose a target (e.g., an OpenAI‑based chatbot)
export OPENAI_API_KEY=…
# 2. Run a suite of attacks against it
hackagent run --target openai --attacks all --dataset default
# 3. View results locally
hackagent report --format html > report.html
# 4. Optional: launch the interactive dashboard
hackagent web

The CLI shows a TUI with live progress and stores results in a local SQLite file. If you configure an API key for the HackAgent cloud service, the same data can be synced to a remote dashboard.

---

Reporting & responsible use

• Local mode – SQLite database, offline‑only.
• Cloud mode – Syncs to the HackAgent SaaS platform (API key never leaves the CLI process).
• The project includes a Responsible Disclosure guide and a clear policy that testing must be authorized.

---

Project health (as shown in the README)

• Python 3.10+ required, Apache‑2.0 license.
• CI badge, test‑coverage badge, and automated formatting tools (Ruff, uv, Commitizen) indicate an actively maintained codebase.
• Community discussions and a security policy are provided.

---

TL;DR

HackAgent is a purpose‑built, open‑source toolkit for red‑team style security testing of LLM‑powered agents. It supplies a catalog of proven attacks, a generation/judgment loop, and integrations with the major LLM SDKs, all wrapped in a Python package and a cross‑platform CLI.