hackagent 0.13.1__tar.gz → 0.15.0__tar.gz

{hackagent-0.13.1 → hackagent-0.15.0}/.gitignore

@@ -1,5 +1,6 @@
 # Custom
 logs/
+.logs/
 *.sbatch
 .ruff_cache/
 reports/
@@ -147,5 +148,5 @@ 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

{hackagent-0.13.1 → hackagent-0.15.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: hackagent
-Version: 0.13.1
+Version: 0.15.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
@@ -16,20 +16,26 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Requires-Python: >=3.10
 Requires-Dist: click>=8.1.0
-Requires-Dist: datasets>=2.14.0
-Requires-Dist: faiss-cpu>=1.13.2
-Requires-Dist: flask>=3.1.3
 Requires-Dist: httpx>=0.27.0
 Requires-Dist: litellm>=1.69.2
 Requires-Dist: openai>=1.0.0
-Requires-Dist: pillow>=10.0.0
-Requires-Dist: playwright>=1.40
 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
-Requires-Dist: textual>=1.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
 
@@ -91,7 +97,17 @@ source .venv/bin/activate
 pip install hackagent
 ```
 
-No API key required: HackAgent works locally out of the box.
+No API key required: HackAgent works locally out of the box. The base install
+imports without the interface and technique extras:
+
+```bash
+pip install 'hackagent[tui]'      # textual
+pip install 'hackagent[web]'      # flask and the dashboard bundle
+pip install 'hackagent[browser]'  # playwright
+pip install 'hackagent[rag]'      # faiss and numpy
+pip install 'hackagent[vision]'   # Pillow
+pip install 'hackagent[hf]'       # HuggingFace datasets
+```
 
 ### Standalone binary (no Python required)
 
@@ -102,17 +118,16 @@ self-contained archive per platform:
 |----------|-------|
 | Linux x86_64 | `hackagent-<version>-linux-x86_64.tar.gz` |
 | macOS arm64 | `hackagent-<version>-macos-arm64.tar.gz` |
-| macOS x86_64 | `hackagent-<version>-macos-x86_64.tar.gz` |
 | Windows x86_64 | `hackagent-<version>-windows-x86_64.zip` |
 
 Extract the archive and run the `hackagent` launcher inside it — no Python, `pip`
 or `uv` install needed. Keep the extracted folder intact; the launcher loads the
 libraries next to it.
 
-> **Note:** the `WEB` provider drives a real browser through Playwright, whose
-> browser binaries cannot be embedded in the archive (or in the PyPI package).
-> Before using `hackagent web`-based targets, install them once with
-> `playwright install`.
+> **Note:** the `WEB` provider drives a real browser through Playwright
+> (`pip install 'hackagent[browser]'`). The browser binaries cannot be embedded
+> in the archive (or in the PyPI package). Before using `hackagent web`-based
+> targets, install them once with `playwright install`.
 
 
 Questions? Join [community discussions](https://github.com/AISecurityLab/hackagent/discussions) or email ais@ai4i.it.
@@ -140,8 +155,9 @@ HackAgent uses a modular pipeline to test agent robustness end-to-end.
 
 HackAgent supports both local and remote reporting.
 
-- Local mode stores test results in SQLite, readable offline.
-- Cloud mode syncs runs to the HackAgent remote platform when an API key is configured.
+- A campaign records its results in local SQLite, readable offline.
+- Set `execution.storage.backend: remote` (with `base_url` and `api_key_env`) to
+  send a run to a HackAgent server instead.
 
 `hackagent web` serves the HackAgent dashboard — the same app as
 [app.hackagent.dev](https://app.hackagent.dev) — from your own machine, against
@@ -153,7 +169,7 @@ is never exposed to the browser.
 hackagent web
 ```
 
-Install it with `pip install 'hackagent[web]'`; see the [web command docs](docs/docs/cli/web.md) for modes and options.
+Install it with `pip install 'hackagent[web]'`; see the [web command docs](docs/docs/getting-started/dashboard.mdx) for modes and options.
 
 ## Responsible Use
 

{hackagent-0.13.1 → hackagent-0.15.0}/README.md

@@ -56,7 +56,17 @@ source .venv/bin/activate
 pip install hackagent
 ```
 
-No API key required: HackAgent works locally out of the box.
+No API key required: HackAgent works locally out of the box. The base install
+imports without the interface and technique extras:
+
+```bash
+pip install 'hackagent[tui]'      # textual
+pip install 'hackagent[web]'      # flask and the dashboard bundle
+pip install 'hackagent[browser]'  # playwright
+pip install 'hackagent[rag]'      # faiss and numpy
+pip install 'hackagent[vision]'   # Pillow
+pip install 'hackagent[hf]'       # HuggingFace datasets
+```
 
 ### Standalone binary (no Python required)
 
@@ -67,17 +77,16 @@ self-contained archive per platform:
 |----------|-------|
 | Linux x86_64 | `hackagent-<version>-linux-x86_64.tar.gz` |
 | macOS arm64 | `hackagent-<version>-macos-arm64.tar.gz` |
-| macOS x86_64 | `hackagent-<version>-macos-x86_64.tar.gz` |
 | Windows x86_64 | `hackagent-<version>-windows-x86_64.zip` |
 
 Extract the archive and run the `hackagent` launcher inside it — no Python, `pip`
 or `uv` install needed. Keep the extracted folder intact; the launcher loads the
 libraries next to it.
 
-> **Note:** the `WEB` provider drives a real browser through Playwright, whose
-> browser binaries cannot be embedded in the archive (or in the PyPI package).
-> Before using `hackagent web`-based targets, install them once with
-> `playwright install`.
+> **Note:** the `WEB` provider drives a real browser through Playwright
+> (`pip install 'hackagent[browser]'`). The browser binaries cannot be embedded
+> in the archive (or in the PyPI package). Before using `hackagent web`-based
+> targets, install them once with `playwright install`.
 
 
 Questions? Join [community discussions](https://github.com/AISecurityLab/hackagent/discussions) or email ais@ai4i.it.
@@ -105,8 +114,9 @@ HackAgent uses a modular pipeline to test agent robustness end-to-end.
 
 HackAgent supports both local and remote reporting.
 
-- Local mode stores test results in SQLite, readable offline.
-- Cloud mode syncs runs to the HackAgent remote platform when an API key is configured.
+- A campaign records its results in local SQLite, readable offline.
+- Set `execution.storage.backend: remote` (with `base_url` and `api_key_env`) to
+  send a run to a HackAgent server instead.
 
 `hackagent web` serves the HackAgent dashboard — the same app as
 [app.hackagent.dev](https://app.hackagent.dev) — from your own machine, against
@@ -118,7 +128,7 @@ is never exposed to the browser.
 hackagent web
 ```
 
-Install it with `pip install 'hackagent[web]'`; see the [web command docs](docs/docs/cli/web.md) for modes and options.
+Install it with `pip install 'hackagent[web]'`; see the [web command docs](docs/docs/getting-started/dashboard.mdx) for modes and options.
 
 ## Responsible Use
 

hackagent-0.15.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.15.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.15.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.15.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.15.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.13.1/hackagent/attacks/generator → hackagent-0.15.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.15.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.15.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.15.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"]