hackagent 0.14.0__tar.gz → 0.16.0__tar.gz

{hackagent-0.14.0 → hackagent-0.16.0}/.gitignore

@@ -1,5 +1,6 @@
 # Custom
 logs/
+.logs/
 *.sbatch
 .ruff_cache/
 reports/
@@ -71,6 +72,7 @@ htmlcov/
 .cache
 nosetests.xml
 coverage.xml
+coverage.json
 *.cover
 .hypothesis/
 .pytest_cache/
@@ -147,5 +149,9 @@ tests/e2e/attacks/
 snapshot_report.html
 
 # Web UI bundle (built by scripts/build_webui.sh)
-hackagent/server/webui/static/*
-!hackagent/server/webui/static/.gitignore
+hackagent/interfaces/web/static/*
+!hackagent/interfaces/web/static/.gitignore
+
+# Results exported from the TUI (hackagent/interfaces/tui/views/results/export.py)
+hackagent_results_*.csv
+hackagent_results_*.json

hackagent-0.16.0/PKG-INFO

@@ -0,0 +1,121 @@
+Metadata-Version: 2.5
+Name: hackagent
+Version: 0.16.0
+Summary: HackAgent is an open-source security toolkit to detect vulnerabilities of your AI Agents.
+Author-email: AI Security Lab <ais@ai4i.it>
+License: Apache-2.0
+License-File: LICENSE
+Keywords: agents,ai,security,testing,vulnerabilities
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Requires-Dist: click>=8.1.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: litellm>=1.69.2
+Requires-Dist: openai>=1.0.0
+Requires-Dist: pydantic[email]>=2.0
+Requires-Dist: python-dateutil>=2.8.0
+Requires-Dist: pyyaml>=6.0.0
+Requires-Dist: rich>=14.0.0
+Provides-Extra: browser
+Requires-Dist: playwright>=1.40; extra == 'browser'
+Provides-Extra: hf
+Requires-Dist: datasets>=2.14.0; extra == 'hf'
+Provides-Extra: rag
+Requires-Dist: faiss-cpu>=1.13.2; extra == 'rag'
+Requires-Dist: numpy>=1.26; extra == 'rag'
+Provides-Extra: tui
+Requires-Dist: textual>=1.0.0; extra == 'tui'
+Provides-Extra: vision
+Requires-Dist: pillow>=10.0.0; extra == 'vision'
+Provides-Extra: web
+Requires-Dist: flask>=3.1.3; extra == 'web'
+Requires-Dist: hackagent-webui<1.0,>=0.2; extra == 'web'
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+<img src="https://docs.hackagent.dev/img/banner.svg" alt="HackAgent" width="800">
+
+**The open-source red-team toolkit for AI models and agents**
+
+[Docs](https://docs.hackagent.dev/) · [App](https://app.hackagent.dev/) · [API](https://api.hackagent.dev/schema/redoc)
+
+[![PyPI](https://img.shields.io/pypi/v/hackagent)](https://pypi.org/project/hackagent/)
+![Python](https://img.shields.io/badge/python-3.10%2B-blue)
+![License](https://img.shields.io/badge/license-Apache%202.0-green)
+![CI](https://img.shields.io/github/actions/workflow/status/AISecurityLab/hackagent/ci.yml)
+![Coverage](https://img.shields.io/codecov/c/github/AISecurityLab/hackagent)
+
+</div>
+
+HackAgent attacks your AI model or agent with research-backed techniques —
+jailbreaks, prompt injection, tool misuse — and has judge models score every
+reply. You get a measured success rate per attack, so you can see how exposed a
+target is and whether a fix helped.
+
+## See it run
+
+**Terminal UI.** Start from an example, change what you need, run it.
+
+<img src="https://raw.githubusercontent.com/AISecurityLab/hackagent/main/docs/static/gifs/hackagent-tui.gif" alt="Building and running a campaign in the HackAgent terminal UI" width="100%">
+
+**Command line.** The same campaign is one YAML file you can edit, check and run, in a shell or in CI.
+
+<img src="https://raw.githubusercontent.com/AISecurityLab/hackagent/main/docs/static/gifs/hackagent-cli.gif" alt="Copying, editing, validating and running a campaign from the command line" width="100%">
+
+**Dashboard.** Browse runs, results and traces with `hackagent web`, or on [app.hackagent.dev](https://app.hackagent.dev/).
+
+<img src="https://raw.githubusercontent.com/AISecurityLab/hackagent/main/docs/static/gifs/hackagent-dashboard.gif" alt="Browsing campaign results in the HackAgent dashboard" width="100%">
+
+## Quick start
+
+```bash
+pip install 'hackagent[tui]'
+hackagent                # opens the terminal UI
+```
+
+Or run an example end to end, fully local, with [Ollama](https://ollama.com):
+
+```bash
+ollama pull gemma3:4b
+hackagent examples copy h4rm3l-demo
+hackagent campaign run h4rm3l-demo.yaml
+```
+
+No API key needed: results go to a local database unless a campaign says
+otherwise.
+
+## Learn more
+
+- [Installation](https://docs.hackagent.dev/getting-started/installation) — extras, and standalone binaries that need no Python
+- [Your first campaign](https://docs.hackagent.dev/getting-started/first-campaign) — write, check and run one
+- [Concepts](https://docs.hackagent.dev/concepts) — attacks, judges and how a run works
+- [Attacks](https://docs.hackagent.dev/reference/attacks) and the [campaign file reference](https://docs.hackagent.dev/reference/campaign)
+- [Dashboard](https://docs.hackagent.dev/getting-started/dashboard) — `hackagent web`, locally or against your account
+
+Questions? Join the [discussions](https://github.com/AISecurityLab/hackagent/discussions) or email ais@ai4i.it.
+
+## Responsible use
+
+HackAgent is for authorized security testing only. Test systems you own or
+have written permission to test, and report what you find through coordinated
+disclosure. Read the [responsible disclosure guidelines](https://docs.hackagent.dev/security/responsible-disclosure)
+and our [security policy](SECURITY.md).
+
+## Contributing
+
+Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) and
+[CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).
+
+## License
+
+Licensed under Apache-2.0. See [LICENSE](LICENSE). HackAgent is intended for
+security research and AI safety improvement; the authors are not responsible
+for misuse.

hackagent-0.16.0/README.md

@@ -0,0 +1,80 @@
+<div align="center">
+
+<img src="https://docs.hackagent.dev/img/banner.svg" alt="HackAgent" width="800">
+
+**The open-source red-team toolkit for AI models and agents**
+
+[Docs](https://docs.hackagent.dev/) · [App](https://app.hackagent.dev/) · [API](https://api.hackagent.dev/schema/redoc)
+
+[![PyPI](https://img.shields.io/pypi/v/hackagent)](https://pypi.org/project/hackagent/)
+![Python](https://img.shields.io/badge/python-3.10%2B-blue)
+![License](https://img.shields.io/badge/license-Apache%202.0-green)
+![CI](https://img.shields.io/github/actions/workflow/status/AISecurityLab/hackagent/ci.yml)
+![Coverage](https://img.shields.io/codecov/c/github/AISecurityLab/hackagent)
+
+</div>
+
+HackAgent attacks your AI model or agent with research-backed techniques —
+jailbreaks, prompt injection, tool misuse — and has judge models score every
+reply. You get a measured success rate per attack, so you can see how exposed a
+target is and whether a fix helped.
+
+## See it run
+
+**Terminal UI.** Start from an example, change what you need, run it.
+
+<img src="https://raw.githubusercontent.com/AISecurityLab/hackagent/main/docs/static/gifs/hackagent-tui.gif" alt="Building and running a campaign in the HackAgent terminal UI" width="100%">
+
+**Command line.** The same campaign is one YAML file you can edit, check and run, in a shell or in CI.
+
+<img src="https://raw.githubusercontent.com/AISecurityLab/hackagent/main/docs/static/gifs/hackagent-cli.gif" alt="Copying, editing, validating and running a campaign from the command line" width="100%">
+
+**Dashboard.** Browse runs, results and traces with `hackagent web`, or on [app.hackagent.dev](https://app.hackagent.dev/).
+
+<img src="https://raw.githubusercontent.com/AISecurityLab/hackagent/main/docs/static/gifs/hackagent-dashboard.gif" alt="Browsing campaign results in the HackAgent dashboard" width="100%">
+
+## Quick start
+
+```bash
+pip install 'hackagent[tui]'
+hackagent                # opens the terminal UI
+```
+
+Or run an example end to end, fully local, with [Ollama](https://ollama.com):
+
+```bash
+ollama pull gemma3:4b
+hackagent examples copy h4rm3l-demo
+hackagent campaign run h4rm3l-demo.yaml
+```
+
+No API key needed: results go to a local database unless a campaign says
+otherwise.
+
+## Learn more
+
+- [Installation](https://docs.hackagent.dev/getting-started/installation) — extras, and standalone binaries that need no Python
+- [Your first campaign](https://docs.hackagent.dev/getting-started/first-campaign) — write, check and run one
+- [Concepts](https://docs.hackagent.dev/concepts) — attacks, judges and how a run works
+- [Attacks](https://docs.hackagent.dev/reference/attacks) and the [campaign file reference](https://docs.hackagent.dev/reference/campaign)
+- [Dashboard](https://docs.hackagent.dev/getting-started/dashboard) — `hackagent web`, locally or against your account
+
+Questions? Join the [discussions](https://github.com/AISecurityLab/hackagent/discussions) or email ais@ai4i.it.
+
+## Responsible use
+
+HackAgent is for authorized security testing only. Test systems you own or
+have written permission to test, and report what you find through coordinated
+disclosure. Read the [responsible disclosure guidelines](https://docs.hackagent.dev/security/responsible-disclosure)
+and our [security policy](SECURITY.md).
+
+## Contributing
+
+Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) and
+[CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).
+
+## License
+
+Licensed under Apache-2.0. See [LICENSE](LICENSE). HackAgent is intended for
+security research and AI safety improvement; the authors are not responsible
+for misuse.

hackagent-0.16.0/hackagent/__init__.py

@@ -0,0 +1,33 @@
+# Copyright 2026 - AI4I. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""A client library for HackAgent — AI Agent Security Testing.
+
+The package root exports the facade and public types only. Importing it does
+not install a logging handler and does not import interface toolkits.
+"""
+
+from hackagent.client import HackAgent
+from hackagent.core.contracts import AgentType
+from hackagent.core.errors import ApiError, HackAgentError
+from hackagent.core.settings import (
+    DEFAULT_REMOTE_BASE_URL,
+    Settings,
+    Source,
+    read_config_file,
+    resolve_ollama_base_url,
+    resolve_remote_base_url,
+)
+
+__all__ = (
+    "AgentType",
+    "ApiError",
+    "DEFAULT_REMOTE_BASE_URL",
+    "HackAgent",
+    "HackAgentError",
+    "Settings",
+    "Source",
+    "read_config_file",
+    "resolve_ollama_base_url",
+    "resolve_remote_base_url",
+)

hackagent-0.16.0/hackagent/attacks/__init__.py

@@ -0,0 +1,12 @@
+# Copyright 2026 - AI4I. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""
+Attack techniques for the HackAgent security assessment framework.
+
+Techniques live under ``techniques/``. The composition root that runs them
+is :mod:`hackagent.orchestrator`. Judges live in ``hackagent.evaluation``.
+Run records live in ``hackagent.tracking``.
+"""
+
+__all__: list[str] = []

hackagent-0.16.0/hackagent/attacks/_lib/__init__.py

@@ -0,0 +1,22 @@
+# Copyright 2026 - AI4I. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Shared attack helpers.
+
+Depth-0 techniques import only ``hackagent.core`` and this package — not
+other depth-0 packages or sibling techniques. What remains here is the live
+set: response extraction (shared with the model layer), prompt parsing,
+templating transforms, and the graphviz helper.
+"""
+
+from hackagent.attacks._lib.response import (
+    extract_response_content,
+    get_guardrail_info,
+    is_guardrail_response,
+)
+
+__all__ = [
+    "extract_response_content",
+    "get_guardrail_info",
+    "is_guardrail_response",
+]

hackagent-0.16.0/hackagent/attacks/_lib/graphviz.py

@@ -0,0 +1,21 @@
+# Copyright 2026 - AI4I. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Graphviz bootstrap for flowchart rendering (FC-Attack).
+
+``ensure_graphviz()`` is the public entry point used by interfaces and
+the FC renderer.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+
+def ensure_graphviz(allow_download: Optional[bool] = None) -> Optional[str]:
+    """Ensure Graphviz ``dot`` is available and return its resolved path."""
+    from hackagent.attacks.techniques.static.fc.flowchart_renderer import (
+        ensure_graphviz,
+    )
+
+    return ensure_graphviz(allow_download=allow_download)

hackagent-0.16.0/hackagent/attacks/_lib/response.py

@@ -0,0 +1,84 @@
+# Copyright 2026 - AI4I. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Response helpers for attack modules.
+
+Prefer :class:`~hackagent.core.contracts.Completion` properties
+(``text``, ``ok``, ``blocked``, ``guardrail_info``). These helpers keep
+legacy envelope/dict and OpenAI-style objects working until every
+technique calls ``LLM.complete``.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Dict, Optional
+
+from hackagent.core.contracts import Completion
+
+logger = logging.getLogger("hackagent.attacks._lib.response")
+
+GUARDRAIL_ADAPTER_TYPE = "guardrail"
+GUARDRAIL_BLOCKED_MSG = "Blocked by guardrail"
+
+
+def extract_response_content(
+    response: Any,
+    logger: Optional[logging.Logger] = None,
+) -> Optional[str]:
+    """Extract text content from a Completion or legacy LLM response."""
+    if response is None:
+        return None
+
+    log = logger or globals()["logger"]
+
+    if isinstance(response, Completion):
+        return response.text or None
+
+    # OpenAI-style object with choices attribute
+    if hasattr(response, "choices") and response.choices:
+        try:
+            message = response.choices[0].message
+            content = message.content if message else None
+            return content or None
+        except (AttributeError, IndexError) as e:
+            log.debug(f"Failed to extract from OpenAI-style response: {e}")
+
+    if isinstance(response, dict):
+        content = response.get("generated_text") or response.get("processed_response")
+        if content:
+            return content
+        error_msg = response.get("error_message")
+        if error_msg:
+            log.debug(f"Response contains error: {error_msg}")
+            return None
+
+    if isinstance(response, str):
+        return response if response else None
+
+    # Duck-typed Completion-like (e.g. FakeLLM extras)
+    text = getattr(response, "text", None)
+    if isinstance(text, str):
+        return text or None
+
+    return None
+
+
+def is_guardrail_response(response: Any) -> bool:
+    """Return True if *response* is a guardrail-blocked response."""
+    if isinstance(response, Completion):
+        return response.blocked
+    if not isinstance(response, dict):
+        return False
+    return response.get("adapter_type") == GUARDRAIL_ADAPTER_TYPE
+
+
+def get_guardrail_info(response: Any) -> Dict[str, Any]:
+    """Extract guardrail metadata from a blocked response."""
+    if isinstance(response, Completion):
+        return response.guardrail_info
+    if not is_guardrail_response(response):
+        return {}
+    if isinstance(response, dict):
+        return response.get("agent_specific_data") or {}
+    return {}

{hackagent-0.14.0/hackagent/attacks/generator → hackagent-0.16.0/hackagent/attacks/_lib}/templates.py

@@ -15,7 +15,7 @@ Constants:
     SUCCESS_PATTERNS: Regex patterns for detecting successful attacks
 
 Usage:
-    from hackagent.attacks.generator.templates import (
+    from hackagent.attacks._lib.templates import (
         AttackTemplates,
         REFUSAL_PATTERNS,
         SUCCESS_PATTERNS,
@@ -25,7 +25,7 @@ Usage:
 import codecs
 from typing import List
 
-from hackagent.attacks.shared.utils import encode_base64
+from hackagent.attacks._lib.transforms import encode_base64
 
 
 class AttackTemplates:

hackagent-0.16.0/hackagent/attacks/techniques/__init__.py

@@ -0,0 +1,31 @@
+# Copyright 2026 - AI4I. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""
+Attack techniques module.
+
+Techniques define HOW we generate attacks. Each technique is a complete
+implementation that can target different objectives.
+
+Techniques are grouped by category, the same grouping the docs use:
+
+- static/: fixed transforms, no attacker refinement loop (baseline,
+  static_template, flipattack, cipherchat, h4rm3l, mml, fc/tfc)
+- adaptive/: independent attempts that refine or search (pair, tap, pap,
+  bon, advprefix, autodan_turbo)
+- multi_turn/: one growing conversation with the target (crescendo)
+- indirect/: payload delivered through retrieved content or tool output
+  (rag, tool_output_ipi)
+
+The folder follows :mod:`hackagent.catalog.taxonomy`: the ``indirect`` tag
+decides first, otherwise the primary category does.
+
+Every technique package holds:
+    1. attack.py - a ``StaticAttack`` or ``IterativeAttack`` subclass
+    2. config.py - its ``AttackParams``: parameters and role fields
+
+:mod:`.contract` holds what every attack depends on, :mod:`.registry` maps a
+campaign's attack name to its class, and :mod:`.trace` records what a run did.
+"""
+
+__all__ = []

hackagent-0.16.0/hackagent/attacks/techniques/adaptive/__init__.py

@@ -0,0 +1,10 @@
+# Copyright 2026 - AI4I. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Adaptive techniques.
+
+Many independent attempts that refine or search, without a shared growing
+conversation: pair, tap, pap, bon, advprefix, and autodan_turbo.
+
+Importing this package does not import the techniques in it.
+"""

hackagent-0.16.0/hackagent/attacks/techniques/adaptive/advprefix/__init__.py

@@ -0,0 +1,12 @@
+# Copyright 2026 - AI4I. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""AdvPrefix: write the opening the target will finish.
+
+Based on: https://arxiv.org/abs/2412.10321
+"""
+
+from .attack import AdvPrefixAttack
+from .config import AdvPrefixParams
+
+__all__ = ["AdvPrefixAttack", "AdvPrefixParams"]