hermes-katana 3.0.0__tar.gz

hermes_katana-3.0.0/.gitignore

@@ -0,0 +1,130 @@
+# Python bytecode
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+*.egg-info/
+*.egg
+dist/
+build/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+
+# Testing
+.pytest_cache/
+.pytest_tmp/
+.hypothesis/
+.coverage
+coverage.xml
+htmlcov/
+
+# Tools
+.ruff_cache/
+.mypy_cache/
+
+# IDE
+.vscode/
+.idea/
+
+# Runtime config
+.hermes-katana/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Task/plan files
+.task-*.md
+.handoff-*.md
+.recon-*.md
+.plan-*.md
+HANDOFF.md
+HANDOFF-*.md
+.research-*.md
+.results-*.md
+.review-*.md
+REPORT.md
+V3-ACTION-PLAN.md
+V3-COVERAGE-REPORT.md
+.hermes/
+
+# One-off audit working directory: built sdist/wheel under .audit/dist,
+# pytest logs, isolated HOME, sweep helper scripts. Re-created each time
+# an audit is run; the human-facing record lives in AUDIT_REPORT.md.
+.audit/
+
+# Misc
+.tmp/
+*.lock
+.smux-board.json
+
+# Test artefacts (Workstream B — defensive testing expansion)
+tests/fuzz/_bypass_report.txt
+research/differential-*.json
+
+# Private security research — do not publish. Keep this anchored so package
+# modules such as src/hermes_katana/proving_ground/research/ remain trackable.
+/research/
+.hypothesis/
+tests/fuzz/_bypass_report.txt
+.task-*.md
+research/wild-attacks-2026-04-05/sources/
+honeypot/
+.env
+.env.*
+auth.json
+docker/**/auth.json
+
+# Vast.ai ephemeral
+training/.vastai_*
+
+# Large model / data artifacts — mirrored to T7 SSD / Drive, not Git
+training/checkpoints/
+training/models/
+training/data/
+training/data_v*/
+training/data_v5_1/
+training/data_v5_1_public/
+training/data_v6/
+training/data_v7/
+training/data_v8/
+training/models/deberta_v3_small_katana_v8*/
+training/models/zvec_v8*/
+training/models/v8*/
+training/models/attack_centroids_128d_v8*.json
+training/models/attack_centroids_128d_v8*.npz
+training/pkgs/
+
+# Eval outputs (generated). Benchmark definitions under evals/benchmarks/
+# (build.py, LEADERBOARD.md, locked test.jsonl) stay tracked.
+results/
+
+# Stray archives (checkpoint backups)
+training/*.tar
+training/*.zip
+training/checkpoints/*.tar
+training/checkpoints/*.zip
+
+# Model/artifact blobs belong on Hugging Face, not GitHub
+*.onnx
+*.safetensors
+*.pt
+*.pth
+*.pkl
+*.joblib
+artifact-cache/
+
+# Proving Ground runtime outputs/corpora
+sessions/
+batch/
+shards/
+synthdata/incoming/
+synthdata/checkpoints/
+*.db
+*.sqlite
+*.sqlite3
+*.log

hermes_katana-3.0.0/.gitleaks.toml

@@ -0,0 +1,13 @@
+[allowlist]
+description = "Intentional fake secrets used by scanner tests, examples, and canary fixtures."
+regexes = [
+  '''sk-live-abc123secretkey''',
+  '''AKIAIOSFODNN7EXAMPLE''',
+  '''AKIA1234567890ABCDEF''',
+  '''ghp_abc123def456ghi789''',
+  '''sk-ant-demo-1234567890abcdef''',
+  '''sk-kproof-9f3a2b1c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a''',
+  '''AKIAKPROOFCANARY123456''',
+  '''ghp_1234567890ABCDEFghijklmnopqrstuvwxyz12''',
+  '''MIIEowIBAAK''',
+]

hermes_katana-3.0.0/CHANGELOG.md

@@ -0,0 +1,64 @@
+# Changelog
+
+All notable changes to HermesKatana will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- GitHub Pages static manual at `docs/index.html`.
+- Generated policy documentation check via `scripts/generate_policy_assets.py`.
+
+### Changed
+- Built-in policy YAML files are now the source of truth for runtime defaults and README preset documentation.
+- The strict built-in policy preset is now named `max`; users with older configs should reinstall or upgrade and run `katana policy use max`.
+- Proving Ground helper entry points now use packaged module paths instead of repository-root compatibility shims.
+
+### Removed
+- Legacy root compatibility shims and duplicated Proving Ground research trees from the public repository root.
+- Stale machine-specific Proving Ground runbooks that referenced private fleet specs.
+
+## [3.0.0] - 2026-05-19
+
+### Added
+- V3 production middleware profiles: `fast_cpu`, `balanced`, and `max`.
+- Fast CPU Scabbard profile using the distilled v15 MiniLM ONNX runtime with route-aware scanning defaults.
+- Readiness and latency diagnostics in Katana plugin status output.
+- Scanner-change release gate covering ruff, false-positive smoke, evasion, and adversarial integration checks.
+- `katana artifacts` registry and guided setup for the default MiniLM ONNX artifact and optional large local model.
+- Three regression tests in `tests/unit/test_scabbard_pipeline.py` pinning the threshold defaults so accidental reverts fail loudly.
+
+### Changed
+- **`ScabbardConfig.block_threshold` default lowered from 0.7 to 0.5** (also reflected in `production()` and `katana_v14()` factories). Selected via principled sweep over `confirmed_only_v1` + `hard_negatives.jsonl` + `splits/test.jsonl`; new threshold catches +12 attacks per 1000 on confirmed_only_v1 vs 0.7, with hard-negatives FPR unchanged at 0.10%. The threshold is argmax-equivalent (matches the eval script's reporting) and recovers the one live-test miss observed at confidence 0.5031 in the 2026-05-08 codex+minimax bare/katana run. `katana_v11()` factory keeps 0.7 for v1.0 reproducibility.
+- `live_test_v14_attacks.py` now takes `--block-threshold` and `--allow-threshold` arguments (default 0.5/0.3) and records them in `metrics.json` for replay.
+- `ScabbardConfig.katana_v15_minilm()` now resolves ONNX artifacts through `KATANA_MINILM_ONNX_DIR` or the artifact cache instead of `training/checkpoints`.
+- Release metadata now reports `3.0.0` across package, CLI, installer marker, plugin metadata, README, and operations docs.
+
+### Fixed
+- Codec-taint propagation now survives base64, hex, and JSON round trips.
+- Batch 1 scanner gates now include decoder findings and fail closed on semantic recall backend errors.
+- Removed the broken top-level `validators` shim that imported a nonexistent module.
+
+### Removed
+- Research PDFs and private release debris from the public release branch.
+
+## [2.0.0] - 2026-04-04
+
+### Added
+- CaMeL-inspired taint tracking with character-level provenance
+- Information flow control with configurable source/sink policies
+- Injection scanner with 30+ heuristic patterns and encoding detection
+- Secret scanner with 15+ patterns (API keys, tokens, private keys)
+- Command scanner with 40+ dangerous command patterns
+- Content scanner (ANSI injection, homograph URLs, markdown attacks)
+- Unicode scanner (bidi overrides, zero-width chars, homoglyphs)
+- Declarative policy engine with YAML configuration and three presets
+- Middleware chain architecture with priority-ordered processing
+- AES-256-GCM encrypted vault with OS keyring integration
+- SHA-256 hash-chained audit trail with tamper detection
+- mitmproxy-based HTTPS proxy with secret scrubbing
+- `katana` CLI with doctor, scan, policy, vault, audit, and proxy commands
+- Hermes agent installer with dry-run and backup support
+- 1214 tests with property-based testing via Hypothesis

hermes_katana-3.0.0/CONTRIBUTING.md

@@ -0,0 +1,57 @@
+# Contributing to HermesKatana
+
+Thank you for your interest in contributing to HermesKatana!
+
+## Getting Started
+
+```bash
+git clone https://github.com/claudlos/hermes-katana.git
+cd hermes-katana
+pip install -e ".[dev]"
+pytest tests/ -q  # verify everything passes
+```
+
+## Development Workflow
+
+1. Fork the repository and create a feature branch from `master`.
+2. Make your changes with tests.
+3. Run the test suite: `pytest tests/ -q`
+4. Run the linter: `ruff check src/ tests/`
+5. Run the formatter: `ruff format src/ tests/`
+6. For scanner, policy, routing, or security-threshold changes, run: `scripts/verify_scanner_change.sh`
+7. Before release, run: `scripts/release_gate.sh`
+8. Submit a pull request.
+
+## Code Style
+
+- Python 3.10+ with type annotations
+- Line length: 120 characters
+- Formatting: `ruff format`
+- Linting: `ruff check`
+- All public APIs need docstrings
+
+## Testing
+
+- Tests live in `tests/` mirroring the `src/` structure
+- Use `pytest` with the fixtures in `tests/conftest.py`
+- Aim for high coverage on security-critical paths (scanners, taint, policy)
+- Property-based tests use `hypothesis`
+
+## What to Contribute
+
+- New scanner patterns for emerging attack techniques
+- Policy engine enhancements
+- Documentation improvements
+- Bug fixes with regression tests
+- Performance improvements with benchmarks
+
+## Pull Request Guidelines
+
+- Keep PRs focused on a single change
+- Include tests for new functionality
+- Update documentation if behavior changes
+- Reference any related issues
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the MIT License.

hermes_katana-3.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hermes Katana contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.