agenthacker 0.1.0__tar.gz

agenthacker-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,55 @@
+name: Release
+
+# Build the agenthacker wheel + sdist on a version tag and publish to PyPI via
+# Trusted Publishing (OIDC) — no API token is stored in the repo.
+#
+# PREREQUISITE: configure a PyPI Trusted Publisher for this repo + this workflow
+# filename + the `pypi` environment, and reserve the project name. Until then the
+# publish step fails by design — nothing is published without the PyPI-side trust
+# link. Release with `git tag vX.Y.Z && git push origin vX.Y.Z`. PyPI versions are
+# immutable: never re-tag a released version.
+
+on:
+  push:
+    tags:
+      - "v[0-9]+.[0-9]+.[0-9]+"
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: build distributions
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build wheel + sdist
+        run: |
+          pip install build
+          python -m build --outdir dist
+      - name: Verify metadata
+        run: |
+          pip install twine
+          twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write   # required for Trusted Publishing (OIDC)
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

agenthacker-0.1.0/.github/workflows/sdk.yml

@@ -0,0 +1,85 @@
+name: CI
+
+# Continuous integration for the agenthacker SDK (import name firewall_sdk).
+# Local-first, no AWS/backend needed.
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: tests (py${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install with dev extras
+        run: pip install ".[dev]"
+      - name: Run unit tests
+        run: pytest tests/firewall_sdk -q
+
+  lint:
+    name: lint (ruff)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install ruff==0.15.20
+      - name: ruff check
+        run: ruff check src/firewall_sdk
+      - name: ruff format --check
+        run: ruff format --check src/firewall_sdk
+
+  types:
+    name: types (mypy)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install (for import resolution) + mypy
+        run: |
+          pip install ".[dev]"
+          pip install mypy==2.1.0
+      - name: mypy
+        run: mypy --config-file pyproject.toml src/firewall_sdk
+
+  rules:
+    name: rule-catalog drift
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install .
+      - name: Check rule_catalog.json is in sync with the SDK source
+        run: python scripts/check_rule_catalog.py
+
+  secrets:
+    name: secret scan (detect-secrets)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install detect-secrets==1.5.0
+      - name: detect-secrets (fail on any secret not in the baseline)
+        run: |
+          detect-secrets-hook --baseline .secrets.baseline \
+            $(git ls-files 'src/*' 'tests/*' 'examples/*' 'scripts/*' 'docs/*' '*.md')

agenthacker-0.1.0/.gitignore

@@ -0,0 +1,55 @@
+# Environment / secrets — never commit real values
+.env
+.env.*
+!.env.example
+secrets.txt
+secrets.json
+*.secret
+*credentials*.json
+
+# Private keys / certs / keystores
+*.pem
+*.key
+*.p12
+*.pfx
+*.keystore
+id_rsa
+id_rsa.*
+id_ed25519
+id_ed25519.*
+
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.venv/
+venv/
+env/
+*.egg-info/
+build/
+dist/
+
+# Test / coverage cache
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Node / frontend build output
+node_modules/
+apps/dashboard-ui/dist/
+
+# Editor / OS
+.DS_Store
+*.swp
+*.swo
+.idea/
+.vscode/
+
+# Local docker compose overrides — never ship one
+docker-compose.override.yml
+
+# Runtime logs / model cache
+logs/
+*.log
+cache/

agenthacker-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,21 @@
+# Pre-commit hooks for the agenthacker SDK. Mirrors the merge gates in
+# .github/workflows/sdk.yml so problems are caught before they reach CI.
+#
+#   pip install pre-commit
+#   pre-commit install
+#   pre-commit run --all-files      # one-off full pass
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.20
+    hooks:
+      - id: ruff            # lint (autofix)
+        args: [--fix]
+        files: ^src/firewall_sdk/
+      - id: ruff-format     # format
+        files: ^src/firewall_sdk/
+
+  - repo: https://github.com/Yelp/detect-secrets
+    rev: v1.5.0
+    hooks:
+      - id: detect-secrets
+        args: ["--baseline", ".secrets.baseline"]

agenthacker-0.1.0/.secrets.baseline

@@ -0,0 +1,187 @@
+{
+  "version": "1.5.0",
+  "plugins_used": [
+    {
+      "name": "ArtifactoryDetector"
+    },
+    {
+      "name": "AWSKeyDetector"
+    },
+    {
+      "name": "AzureStorageKeyDetector"
+    },
+    {
+      "name": "Base64HighEntropyString",
+      "limit": 4.5
+    },
+    {
+      "name": "BasicAuthDetector"
+    },
+    {
+      "name": "CloudantDetector"
+    },
+    {
+      "name": "DiscordBotTokenDetector"
+    },
+    {
+      "name": "GitHubTokenDetector"
+    },
+    {
+      "name": "GitLabTokenDetector"
+    },
+    {
+      "name": "HexHighEntropyString",
+      "limit": 3.0
+    },
+    {
+      "name": "IbmCloudIamDetector"
+    },
+    {
+      "name": "IbmCosHmacDetector"
+    },
+    {
+      "name": "IPPublicDetector"
+    },
+    {
+      "name": "JwtTokenDetector"
+    },
+    {
+      "name": "KeywordDetector",
+      "keyword_exclude": ""
+    },
+    {
+      "name": "MailchimpDetector"
+    },
+    {
+      "name": "NpmDetector"
+    },
+    {
+      "name": "OpenAIDetector"
+    },
+    {
+      "name": "PrivateKeyDetector"
+    },
+    {
+      "name": "PypiTokenDetector"
+    },
+    {
+      "name": "SendGridDetector"
+    },
+    {
+      "name": "SlackDetector"
+    },
+    {
+      "name": "SoftlayerDetector"
+    },
+    {
+      "name": "SquareOAuthDetector"
+    },
+    {
+      "name": "StripeDetector"
+    },
+    {
+      "name": "TelegramBotTokenDetector"
+    },
+    {
+      "name": "TwilioKeyDetector"
+    }
+  ],
+  "filters_used": [
+    {
+      "path": "detect_secrets.filters.allowlist.is_line_allowlisted"
+    },
+    {
+      "path": "detect_secrets.filters.common.is_ignored_due_to_verification_policies",
+      "min_level": 2
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_indirect_reference"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_likely_id_string"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_lock_file"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_not_alphanumeric_string"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_potential_uuid"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_prefixed_with_dollar_sign"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_sequential_string"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_swagger_file"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_templated_secret"
+    }
+  ],
+  "results": {
+    "rule_catalog.json": [
+      {
+        "type": "Secret Keyword",
+        "filename": "rule_catalog.json",
+        "hashed_secret": "d321afb05515c38468450cffa15e3c068f829ada",
+        "is_verified": false,
+        "line_number": 343
+      }
+    ],
+    "tests/firewall_sdk/test_event_store.py": [
+      {
+        "type": "Basic Auth Credentials",
+        "filename": "tests/firewall_sdk/test_event_store.py",
+        "hashed_secret": "9d4e1e23bd5b727046a9e3b4b7db57bd8d6ee684",
+        "is_verified": false,
+        "line_number": 142
+      }
+    ],
+    "tests/firewall_sdk/test_features.py": [
+      {
+        "type": "Base64 High Entropy String",
+        "filename": "tests/firewall_sdk/test_features.py",
+        "hashed_secret": "3a6c8ddd26c465fdcddd7ac90485bfb54dac5ab8",
+        "is_verified": false,
+        "line_number": 72
+      },
+      {
+        "type": "Secret Keyword",
+        "filename": "tests/firewall_sdk/test_features.py",
+        "hashed_secret": "3a6c8ddd26c465fdcddd7ac90485bfb54dac5ab8",
+        "is_verified": false,
+        "line_number": 72
+      }
+    ],
+    "tests/firewall_sdk/test_r08_collapsed_false_positives.py": [
+      {
+        "type": "Base64 High Entropy String",
+        "filename": "tests/firewall_sdk/test_r08_collapsed_false_positives.py",
+        "hashed_secret": "ff6e59edbec3fcff133d7dba55b9c78cfe3be157",
+        "is_verified": false,
+        "line_number": 23
+      },
+      {
+        "type": "Base64 High Entropy String",
+        "filename": "tests/firewall_sdk/test_r08_collapsed_false_positives.py",
+        "hashed_secret": "6ca34167f6574493bc816071212579678f9d4fd0",
+        "is_verified": false,
+        "line_number": 25
+      }
+    ],
+    "tests/firewall_sdk/test_scan_engine.py": [
+      {
+        "type": "AWS Access Key",
+        "filename": "tests/firewall_sdk/test_scan_engine.py",
+        "hashed_secret": "25910f981e85ca04baf359199dd0bd4a3ae738b6",
+        "is_verified": false,
+        "line_number": 127
+      }
+    ]
+  },
+  "generated_at": "2026-07-02T01:36:09Z"
+}

agenthacker-0.1.0/CHANGELOG.md

@@ -0,0 +1,106 @@
+# Changelog
+
+All notable changes to the Firewall SDK will be documented in this file.
+
+Format follows [Keep a Changelog](https://keepachangelog.com/).
+
+## [Unreleased]
+
+### Packaging
+
+- **Distribution renamed to `agenthacker`** for PyPI (`pip install agenthacker`).
+  The **import** name is unchanged — still `from firewall_sdk import Firewall`.
+  `pyproject.toml` maps the distribution to the `src/firewall_sdk` package
+  explicitly.
+- Added a `py.typed` marker so type checkers pick up the SDK's inline types.
+- Expanded package metadata: keywords, trove classifiers, and project URLs.
+
+### Changed
+
+- Cloud HTTP timeout is now configurable via the `AGENTHACKER_HTTP_TIMEOUT`
+  environment variable, a `Firewall(http_timeout=...)` argument, or
+  `CloudClient(..., timeout=...)` (default unchanged at 3s). Raise it for
+  backends with cold-start latency, where the previous fixed 3s could time out
+  and fail open before the backend warmed.
+- Backend throttling (HTTP 429) now emits a one-time warning per endpoint
+  (like 401/403) instead of a silent debug log, so a rate-limited — and thus
+  fail-open, unchecked — agent is visible in logs.
+
+### Fixed
+
+- `configure_features` docstring example referenced `llm_guard`, which is not
+  one of the registry flags and would raise `ValueError`; it now uses real flags.
+
+### Added
+
+- New `lang.py` module — pure-stdlib script/language utilities used across the CP layers:
+  `dominant_scripts`, `is_mostly_non_latin`, `is_mixed_script`, `confusable_skeleton`,
+  `has_latin_confusables`, `script_risk`, `strip_invisible`, `invisible_char_stats`,
+  `has_foreign_segment`
+- Invisible/zero-width Unicode normalization in the regex checkpoint — strips zero-width,
+  variation-selector, and Unicode tag-block characters before matching; any Unicode tag-block
+  character (U+E0000–U+E007F) is now a hard block (R-11) to defeat tag/emoji smuggling
+- Homoglyph (Cyrillic/Greek → ASCII) skeleton pass so confusable-spoofed English attacks match
+  the existing regex (e.g. Cyrillic-spoofed "ignore previous instructions" → R-02)
+- Code-switching / "sandwich" attack detection (`has_foreign_segment`) — a short non-dominant
+  script run buried in benign text now forces the cloud (Bedrock) judge
+- `script_risk_factor()` and an opt-in `extra_factors` parameter on `check_user_risk` — a
+  capped soft behavioural-risk signal for non-Latin/mixed-script/homoglyph input (never a hard block)
+- Optional translate-then-scan layer `translate_guard.py` (new `[translate]` extra) — off by
+  default, advisory; scans a translated copy for the literal English-phrase rule subset only
+- `AGENTHACKER_API_URL` environment override in `cloud_client.configure()` / auto-configure so
+  the SDK can target a local or self-hosted backend
+- Multilingual + obfuscation test coverage: `test_lang.py`, `test_multilingual_semantic.py`,
+  `test_translate_guard.py`, `test_llm_guard.py`, and zero-width/tag-block/homoglyph/CJK cases
+  added to `test_scan_engine.py` and `test_output_guard.py`
+
+### Changed
+
+- Default semantic embedding model → `paraphrase-multilingual-MiniLM-L12-v2` (drop-in 384-dim);
+  override via `FIREWALL_EMBEDDING_MODEL`
+- Default LLM Guard injection model → Meta `Llama-Prompt-Guard-2-86M` (multilingual); override via
+  `FIREWALL_LLM_GUARD_MODEL`; falls back to the English DeBERTa default (never crashes) when the
+  gated model or `HF_TOKEN` is unavailable
+- Regex checkpoint now evaluates each rule against the original text plus the invisible-stripped
+  and homoglyph-skeleton variants (original text still reported in `ScanResult`)
+- `IntentGate.scan_sync` routes non-Latin / mixed-script / foreign-segment input to the cloud
+  judge instead of trusting the English-primary local cosine pass
+- `output_guard` S-01 prompt-leakage detection uses character n-gram shingles for no-space scripts
+  (CJK/Thai); Latin path unchanged
+- LLM judge (`llm_judge.py`), alignment auditor (`alignment_check.py`), and the cloud Bedrock
+  classifier prompt (backend) made explicitly language-agnostic, with a code-switch/sandwich clause
+- `__init__.py` exports `script_risk_factor`; `test_public_api_surface.py` expected surface synced
+- Companion backend changes (outside this package): `apps/backend/db.py` adds a `DB_SSLMODE`
+  override for local/self-hosted Postgres (prod default unchanged)
+
+### Fixed
+
+- S-01 system-prompt-leakage detection silently disabled for no-space scripts (CJK/Thai) due to
+  whitespace word-splitting
+- Homoglyph (Cyrillic/Greek lookalike) and invisible-character obfuscation bypassing the
+  English-only regex checkpoint
+
+### Security
+
+- Detect prompt-injection / jailbreak / out-of-scope / leakage attacks regardless of language,
+  transliteration, code-switching, homoglyph spoofing, or zero-width/tag-block/emoji-smuggling
+  obfuscation, across the regex, embedding, ML-classifier, LLM-judge, and output checkpoints
+  (defense-in-depth; all model/cloud layers remain fail-open)
+
+## [0.1.0] - 2026-03-31
+
+### Added
+
+- Core scan engine with rules R-01 through R-16 (regex-based injection detection, topic scoping, encoding detection, adversarial suffix detection)
+- Four checkpoint scan functions: `scan_input`, `scan_data_field`, `scan_tool_call`, `scan_output`
+- `ScanResult` dataclass and `CLEAN` sentinel
+- Tool guard with `allowed_tools` set and `id_resolver` callable interface
+- Output guard with parameterized `entity_pattern` and `leakage_label` for cross-entity leakage detection
+- LLM Guard integration (optional `[llm_guard]` extra) — semantic scanning via DeBERTa models
+- Invariant Analyzer integration (optional `[invariant]` extra) — trace-level policy evaluation
+- Trace normalization (Anthropic format to OpenAI-compatible format)
+- Structured audit logger with HMAC-hashed email identifiers
+- Agent helpers (provisional) — serialization, trace snapshots, refusal normalization
+- Golden parity corpus validating behavioral equivalence across both agents
+- API surface enforcement test (`test_public_api_surface.py`)
+- `__all__` declarations on all public, semi-public, and provisional modules

agenthacker-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,133 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+**reports@agenthacker.ai**.
+
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations