mnemosyne-guard 0.1.0__tar.gz

mnemosyne_guard-0.1.0/.github/CODEOWNERS

@@ -0,0 +1,8 @@
+# Default owner for everything in the repo
+* @rsh1k
+
+# Security-critical surfaces deserve explicit review
+/src/mnemosyne/policy/   @rsh1k
+/src/mnemosyne/integrity/ @rsh1k
+/src/mnemosyne/detectors/ @rsh1k
+/SECURITY.md             @rsh1k

mnemosyne_guard-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,43 @@
+name: Bug report
+description: Report a defect in Mnemosyne
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for filing a bug. **Do not report security vulnerabilities here** —
+        see [SECURITY.md](../../SECURITY.md) for private disclosure.
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened?
+      description: A clear description of the bug and what you expected instead.
+    validations:
+      required: true
+  - type: textarea
+    id: repro
+    attributes:
+      label: Steps to reproduce
+      description: Minimal code or commands that reproduce the issue.
+      render: python
+    validations:
+      required: true
+  - type: input
+    id: version
+    attributes:
+      label: Mnemosyne version
+      placeholder: "0.1.0"
+    validations:
+      required: true
+  - type: input
+    id: python
+    attributes:
+      label: Python version
+      placeholder: "3.12"
+    validations:
+      required: true
+  - type: textarea
+    id: logs
+    attributes:
+      label: Relevant logs / traceback
+      render: shell

mnemosyne_guard-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Report a security vulnerability
+    url: https://github.com/rsh1k/mnemosyne/security/advisories/new
+    about: Please disclose vulnerabilities privately — do not open a public issue.

mnemosyne_guard-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,33 @@
+name: Feature request
+description: Suggest a capability or improvement
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem / threat
+      description: What gap or ASI06 attack vector does this address?
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed solution
+      description: What should Mnemosyne do? Include detector/policy/API impact if relevant.
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+  - type: checkboxes
+    id: scope
+    attributes:
+      label: Area
+      options:
+        - label: Detector
+        - label: Policy engine
+        - label: Integrity / audit
+        - label: Store / segmentation
+        - label: API / CLI
+        - label: Docs / NIST mapping

mnemosyne_guard-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,23 @@
+## Summary
+
+<!-- What does this change and why? Reference any related issue. -->
+
+## Type of change
+
+- [ ] Bug fix
+- [ ] New feature (detector / policy / endpoint)
+- [ ] Refactor / internal
+- [ ] Docs / NIST mapping
+
+## Security considerations
+
+<!-- Does this touch a trust boundary? If it changes the policy, the cardinal
+     INSTRUCTION-surface invariant, or any detector, explain the threat rationale. -->
+
+## Checklist
+
+- [ ] `make all` passes locally (ruff, mypy, bandit, pytest)
+- [ ] Added/updated tests; security-relevant changes extend the red-team corpus
+- [ ] The cardinal invariant (untrusted content never reaches `INSTRUCTION`) is intact
+- [ ] Updated docs and, if the control catalog changed, ran `python scripts/gen_nist_doc.py`
+- [ ] Updated `CHANGELOG.md`

mnemosyne_guard-0.1.0/.github/dependabot.yml

@@ -0,0 +1,22 @@
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    groups:
+      python-dependencies:
+        patterns: ["*"]
+    labels: ["dependencies"]
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    labels: ["dependencies", "ci"]
+
+  - package-ecosystem: "docker"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    labels: ["dependencies", "docker"]

mnemosyne_guard-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,83 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  quality:
+    name: Lint, type-check & security
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[api,dev]"
+
+      - name: Ruff (lint)
+        run: ruff check src tests
+
+      - name: Mypy (type-check)
+        run: mypy
+
+      - name: Bandit (static security scan)
+        run: bandit -q -r src -c pyproject.toml
+
+      - name: pip-audit (dependency vulnerabilities)
+        run: pip-audit
+
+      - name: NIST doc is in sync with catalog
+        run: |
+          python scripts/gen_nist_doc.py
+          git diff --exit-code docs/NIST_CONTROL_MAPPING.md \
+            || (echo "::error::docs/NIST_CONTROL_MAPPING.md is stale; run 'make docs'" && exit 1)
+
+  test:
+    name: Tests (py${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[api,dev]"
+
+      - name: Run tests
+        run: pytest -q
+
+  docker:
+    name: Build container image
+    runs-on: ubuntu-latest
+    needs: [quality, test]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Build image
+        run: docker build -t mnemosyne-guard:ci .

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

@@ -0,0 +1,47 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+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 sdist and wheel
+        run: |
+          python -m pip install --upgrade pip build
+          python -m build
+      - name: Check 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
+    # Requires a configured PyPI "Trusted Publisher" for this repo + environment.
+    environment: release
+    permissions:
+      id-token: write  # OIDC for trusted publishing; no API token needed
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish
+        uses: pypa/gh-action-pypi-publish@release/v1

mnemosyne_guard-0.1.0/.gitignore

@@ -0,0 +1,45 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+dist/
+*.egg-info/
+.eggs/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+
+# Test / coverage / type-check caches
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+
+# Runtime artifacts
+*.db
+*.sqlite
+*.sqlite3
+*.log
+audit.jsonl
+
+# Secrets / local env (never commit)
+.env
+.env.*
+*.pem
+*.key
+
+# Editor / OS
+.idea/
+.vscode/
+*.swp
+.DS_Store

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

@@ -0,0 +1,39 @@
+# Mnemosyne pre-commit hooks. Install with: pre-commit install
+# Mirrors the CI quality gate so issues are caught before they are pushed.
+minimum_pre_commit_version: "3.5.0"
+
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml
+      - id: check-added-large-files
+      - id: check-merge-conflict
+      - id: detect-private-key
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.6.9
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.11.2
+    hooks:
+      - id: mypy
+        additional_dependencies:
+          - pydantic>=2
+          - pydantic-settings
+        args: ["--config-file=pyproject.toml"]
+        pass_filenames: false
+
+  - repo: https://github.com/PyCQA/bandit
+    rev: 1.7.10
+    hooks:
+      - id: bandit
+        args: ["-c", "pyproject.toml", "-r", "src"]
+        pass_filenames: false

mnemosyne_guard-0.1.0/CHANGELOG.md

@@ -0,0 +1,47 @@
+# Changelog
+
+All notable changes to this project are documented here. 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]
+
+## [0.1.0] - 2026-06-13
+
+### Added
+- **Memory-integrity gateway** with two guarded operations, `guard_write` and
+  `guard_read`, enforcing the cardinal ASI06 invariant: content below the
+  `TRUSTED` tier can never reach an `INSTRUCTION` (control-plane) surface.
+- **Provenance → trust-tier** resolution and **surface**-aware policy
+  (`INSTRUCTION` / `KNOWLEDGE` / `EPISODIC` / `SCRATCH`).
+- **Detectors:**
+  - `injection` — instruction-override, role-reassignment, persistence,
+    tooling/config manipulation, exfiltration, delimiter smuggling, and
+    **delayed/conditional execution** (Gemini-style "delayed tool invocation").
+  - `secrets_pii` — cloud/provider keys, JWTs, private keys, and PII with
+    Luhn-checked card detection; redaction helper.
+  - `anomaly` — size/entropy checks plus a per-writer behavioral baseline with a
+    robust MAD z-score for gradual-erosion ("sleeper agent") detection.
+  - `obfuscation` — invisible-Unicode smuggling: Unicode Tag characters,
+    bidirectional overrides (Trojan Source), and zero-width interleaving, with
+    emoji-ZWJ awareness and a `strip()` sanitiser.
+- **Declarative YAML policy engine** (most-restrictive-wins) with a secure
+  default policy.
+- **Integrity:** HMAC-SHA256 record signing (constant-time verify, KMS/HSM hook)
+  and a hash-chained, tamper-evident audit log with chain verification.
+- **Storage:** `MemoryStore` / `QuarantineStore` protocols with in-memory and
+  SQLite backends; namespace segmentation; human-in-the-loop quarantine
+  promotion that elevates trust to the target surface's requirement.
+- **FastAPI sidecar** (bearer auth) and `mnemosyne` **CLI** (`scan`/`nist`/`version`).
+- **NIST/OWASP control catalog** (MN-01…MN-11) mapping to NIST SP 800-53 Rev 5,
+  SP 800-218A, AI 600-1, and CSF 2.0; surfaced via `GET /v1/compliance`,
+  `mnemosyne nist`, and a generated `docs/NIST_CONTROL_MAPPING.md`.
+- **Telemetry:** structured JSON logging and Prometheus metrics.
+- **Tests:** 131 tests including a red-team corpus that asserts 100% detection
+  of the bundled ASI06 payloads and a 0% false-positive rate on benign writes.
+- **Tooling & ops:** ruff, mypy, bandit, pip-audit, pre-commit, GitHub Actions
+  CI (lint/type/security/test matrix + doc-sync check), Dockerfile,
+  docker-compose, and a release workflow.
+
+[Unreleased]: https://github.com/rsh1k/mnemosyne/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/rsh1k/mnemosyne/releases/tag/v0.1.0

mnemosyne_guard-0.1.0/CITATION.cff

@@ -0,0 +1,29 @@
+cff-version: 1.2.0
+title: "Mnemosyne: A NIST-aligned Memory Integrity & Context-Provenance Firewall for Agentic AI"
+message: "If you use this software, please cite it using these metadata."
+type: software
+authors:
+  - name: "rsh1k"
+    alias: rsh1k
+repository-code: "https://github.com/rsh1k/mnemosyne"
+url: "https://github.com/rsh1k/mnemosyne"
+abstract: >-
+  Mnemosyne is a defense-in-depth library and gateway service that protects the
+  persistent memory and context surfaces of agentic AI systems against OWASP
+  ASI06 (Memory & Context Poisoning). It enforces a provenance-to-trust-tier
+  invariant that prevents untrusted content from reaching instruction
+  (control-plane) surfaces, runs pluggable detectors (injection, secrets/PII,
+  statistical anomaly, and invisible-Unicode obfuscation), signs records with
+  HMAC-SHA256, keeps a hash-chained tamper-evident audit log, and maps its
+  controls to NIST SP 800-53, SP 800-218A, AI 600-1, and CSF 2.0.
+keywords:
+  - ai-security
+  - agentic-ai
+  - owasp
+  - asi06
+  - memory-poisoning
+  - prompt-injection
+  - nist
+license: Apache-2.0
+version: 0.1.0
+date-released: "2026-06-13"

mnemosyne_guard-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,53 @@
+# 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, 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 include
+demonstrating empathy and kindness, being respectful of differing opinions,
+giving and gracefully accepting constructive feedback, accepting responsibility
+and apologizing to those affected by our mistakes, and focusing on what is best
+for the overall community.
+
+Unacceptable behavior includes the use of sexualized language or imagery,
+trolling, insulting or derogatory comments, public or private harassment,
+publishing others' private information without explicit permission, and other
+conduct which could reasonably be considered inappropriate in a professional
+setting.
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards and
+will take appropriate and fair corrective action in response to any behavior
+they deem inappropriate, threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies within all community spaces and also applies when
+an individual is officially representing the community in public spaces.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement via the contact
+listed in the repository profile. All complaints will be reviewed and
+investigated promptly and fairly.
+
+## 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>.
+
+[homepage]: https://www.contributor-covenant.org

mnemosyne_guard-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,80 @@
+# Contributing
+
+Thanks for your interest in improving Mnemosyne. This project guards a security
+boundary, so contributions are held to a high bar for tests and clarity.
+
+## Development setup
+
+```bash
+git clone https://github.com/rsh1k/mnemosyne.git
+cd mnemosyne
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[api,dev]"
+pre-commit install
+```
+
+## The golden rule
+
+Every change is checked by `make all` (lint, type-check, security scan, tests).
+CI runs the same targets. Run it locally before opening a PR:
+
+```bash
+make all
+```
+
+Individual targets:
+
+```bash
+make test        # pytest
+make lint        # ruff
+make typecheck   # mypy
+make security    # bandit + pip-audit
+```
+
+## Tests are mandatory
+
+- New detectors, policy rules, or gateway behaviour **must** come with tests.
+- Security-relevant changes should extend the **red-team corpus**
+  (`tests/test_redteam_corpus.py`). If you add a detection capability, add the
+  attack payloads it catches; if you relax something, prove benign writes still
+  pass. The aggregate detection-rate / false-positive-rate assertions must stay
+  green.
+- The cardinal invariant (untrusted content never reaches the `INSTRUCTION`
+  surface) is sacred. A PR that weakens it will not be merged without an
+  explicit, documented security rationale.
+
+## Adding a detector
+
+1. Implement the `Detector` protocol in `src/mnemosyne/detectors/`.
+2. Return a `ScanResult` of `Finding`s with a `severity`, a `score` in `[0,1]`,
+   and a `metadata["kind"]` (use `secret`/`pii` only for sensitive-data findings
+   — the policy engine routes those through the dedicated secrets rule).
+3. Register it in `default_registry()` (or document it as opt-in).
+4. Add unit tests and, where relevant, corpus entries.
+
+## Changing policy
+
+The default posture lives in `src/mnemosyne/policy/default_policy.yaml`. It is
+security-critical configuration — explain the threat rationale in the PR. Keep
+"most restrictive wins" intact.
+
+## Updating the NIST mapping
+
+The catalog in `src/mnemosyne/nist/__init__.py` is the single source of truth.
+After editing it, regenerate the doc:
+
+```bash
+python scripts/gen_nist_doc.py
+```
+
+## Style
+
+- Code is formatted/linted by `ruff` (line length 100) and type-checked by
+  `mypy`. Public functions get type hints and a docstring explaining the *why*.
+- Prefer clarity over cleverness; this is security code that will be audited.
+
+## Commit / PR hygiene
+
+- Small, focused PRs with a clear description of the threat or behaviour changed.
+- Reference any related issue.
+- By contributing you agree your contributions are licensed under Apache-2.0.

mnemosyne_guard-0.1.0/Dockerfile

@@ -0,0 +1,44 @@
+# syntax=docker/dockerfile:1
+
+# ---- builder ---------------------------------------------------------------
+FROM python:3.12-slim AS builder
+
+ENV PIP_DISABLE_PIP_VERSION_CHECK=1 \
+    PIP_NO_CACHE_DIR=1
+
+WORKDIR /build
+COPY pyproject.toml README.md ./
+COPY src ./src
+
+# Build a wheel so the runtime image installs a clean, pinned artifact.
+RUN pip install --upgrade pip build && python -m build --wheel --outdir /dist
+
+# ---- runtime ---------------------------------------------------------------
+FROM python:3.12-slim AS runtime
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    PIP_DISABLE_PIP_VERSION_CHECK=1 \
+    PIP_NO_CACHE_DIR=1
+
+# Create an unprivileged user to run the service.
+RUN groupadd --system mnemosyne && useradd --system --gid mnemosyne --create-home mnemosyne
+
+WORKDIR /app
+COPY --from=builder /dist/*.whl /tmp/
+RUN pip install /tmp/*.whl "mnemosyne-guard[api]" && rm -f /tmp/*.whl
+
+# Drop privileges.
+USER mnemosyne
+
+EXPOSE 8000
+
+# NOTE: provide a real key at runtime, e.g.
+#   docker run -e MNEMOSYNE_INTEGRITY_KEY=... -e MNEMOSYNE_API_KEYS=... ...
+ENV MNEMOSYNE_LOG_JSON=true
+
+HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
+    CMD python -c "import urllib.request,sys; sys.exit(0 if urllib.request.urlopen('http://127.0.0.1:8000/healthz').status==200 else 1)"
+
+ENTRYPOINT ["uvicorn", "mnemosyne.api.main:factory", "--factory", \
+            "--host", "0.0.0.0", "--port", "8000"]