admission-gate 0.1.0__tar.gz

admission_gate-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ak-skwaa-mahawk
+
+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.

admission_gate-0.1.0/PKG-INFO

@@ -0,0 +1,194 @@
+Metadata-Version: 2.4
+Name: admission-gate
+Version: 0.1.0
+Summary: Deterministic admission gate with human review and cryptographic audit logging for CLI agents.
+Author: ak-skwaa-mahawk
+License: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# admission-gate
+
+[![CI](https://github.com/ak-skwaa-mahawk/admission-gate/actions/workflows/ci.yml/badge.svg)](https://github.com/ak-skwaa-mahawk/admission-gate/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Release](https://img.shields.io/github/v/release/ak-skwaa-mahawk/admission-gate)](https://github.com/ak-skwaa-mahawk/admission-gate/releases)
+
+A lightweight admission gatekeeper and cryptographic audit logger for autonomous CLI agents.
+
+---
+name: Path bypass / policy edge case
+about: Report a path canonicalization escape or policy engine loophole
+title: "[BYPASS]: "
+labels: bug, security
+---
+
+### Environment
+- OS: [e.g. Windows 11, macOS Sonoma, Ubuntu 24.04, Android Termux]
+- Python Version: [e.g. 3.11]
+
+### Proposed Action
+```json
+{
+  "action_id": "test_bypass",
+  "command": "...",
+  "target_path": "...",
+  "risk_tier": 1
+}
+
+
+---
+
+### 3. Add an Integration Example Script
+
+Include a short example script under `examples/agent_tool_example.py` demonstrating how an LLM tool loop hooks into `gated_shell()`:
+
+```python
+"""
+Example: Hooking admission-gate into an agent tool execution loop.
+"""
+
+from admission_gate import ActionProposal, gated_shell
+
+
+def agent_shell_tool(command: str, target: str) -> str:
+    proposal = ActionProposal(
+        action_id="agent_call_001",
+        command=command,
+        target_path=target,
+        risk_tier=2,
+    )
+
+    executed, output, code = gated_shell(
+        proposal,
+        allowed_roots=["./workspace"],
+        log_path="audit_log.jsonl",
+        require_confirm=True,
+    )
+
+    if not executed:
+        return f"Refused by gate: {output}"
+
+    return f"Success (exit code {code}):\n{output}"
+
+
+if __name__ == "__main__":
+    result = agent_shell_tool("ls -la", "./workspace")
+    print(result)
+
+
+
+
+# 1. Create the issue template directory and file
+mkdir -p .github/ISSUE_TEMPLATE
+cat << 'EOF' > .github/ISSUE_TEMPLATE/path_bypass.md
+---
+name: Path bypass / policy edge case
+about: Report a path canonicalization escape or policy engine loophole
+title: "[BYPASS]: "
+labels: bug, security
+---
+
+### Environment
+- OS: [e.g. Windows 11, macOS Sonoma, Ubuntu 24.04, Android Termux]
+- Python Version: [e.g. 3.11]
+
+### Proposed Action
+```json
+{
+  "action_id": "test_bypass",
+  "command": "...",
+  "target_path": "...",
+  "risk_tier": 1
+}
+
+
+
+# admission-gate
+
+A lightweight admission gatekeeper and cryptographic audit logger for autonomous CLI agents.
+
+When local scripts or LLMs execute commands in a subshell, developers are forced between two extremes: fully autonomous execution that risks destructive operations, or prompt fatigue from micro-approving dozens of benign commands. `admission-gate` sits between the agent and your shell:
+
+1. **Deterministic Filter**: Blocks dangerous patterns (`rm -rf /`) and restricts filesystem access to configured `allowed_roots` using strict path canonicalization.
+2. **Interactive TTY Confirmation**: Halts for human authorization (`[y/N]`) only on proposals that pass static policy checks.
+3. **SHA-256 Audit Trail**: Commits all proposals, policy outcomes, and approval decisions to an append-only, hash-chained log.
+
+Requires Python 3.8+ with zero third-party dependencies.
+
+---
+
+## Quickstart
+
+```bash
+git clone [https://github.com/ak-skwaa-mahawk/admission-gate.git](https://github.com/ak-skwaa-mahawk/admission-gate.git)
+cd admission-gate
+pip install .
+```
+
+---
+
+## Library Usage
+
+Wrap your agent's shell execution tool so rejected actions never hit the subshell:
+
+```python
+from admission_gate import ActionProposal, gated_shell
+
+proposal = ActionProposal(
+    action_id="task_101",
+    command="rm scratch.tmp",
+    target_path="./workspace/scratch.tmp",
+    risk_tier=2,
+)
+
+# Returns (executed: bool, output: str, exit_code: int)
+executed, output, code = gated_shell(
+    proposal,
+    allowed_roots=["./workspace"],
+    log_path="audit_log.jsonl",
+    require_confirm=True,
+)
+
+if not executed:
+    print(f"Action refused: {output}")
+else:
+    print(f"Command succeeded:\n{output}")
+```
+
+### Standalone Policy Checks
+
+```python
+from admission_gate import ActionProposal, evaluate
+
+p = ActionProposal("chk_1", "cat /etc/shadow", "/etc/shadow", 1)
+passed, reason = evaluate(p)
+# passed -> False
+# reason -> "Blocked: path resolves to protected directory '/etc'"
+```
+
+---
+
+## Verifying Audit Log Integrity
+
+```bash
+python3 src/admission_gate/verify.py audit_log.jsonl
+```
+
+---
+
+## Running Tests
+
+```bash
+PYTHONPATH=src python3 -m unittest discover -s tests
+```
+
+---
+
+## License
+
+[MIT](LICENSE)

admission_gate-0.1.0/README.md

@@ -0,0 +1,180 @@
+# admission-gate
+
+[![CI](https://github.com/ak-skwaa-mahawk/admission-gate/actions/workflows/ci.yml/badge.svg)](https://github.com/ak-skwaa-mahawk/admission-gate/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Release](https://img.shields.io/github/v/release/ak-skwaa-mahawk/admission-gate)](https://github.com/ak-skwaa-mahawk/admission-gate/releases)
+
+A lightweight admission gatekeeper and cryptographic audit logger for autonomous CLI agents.
+
+---
+name: Path bypass / policy edge case
+about: Report a path canonicalization escape or policy engine loophole
+title: "[BYPASS]: "
+labels: bug, security
+---
+
+### Environment
+- OS: [e.g. Windows 11, macOS Sonoma, Ubuntu 24.04, Android Termux]
+- Python Version: [e.g. 3.11]
+
+### Proposed Action
+```json
+{
+  "action_id": "test_bypass",
+  "command": "...",
+  "target_path": "...",
+  "risk_tier": 1
+}
+
+
+---
+
+### 3. Add an Integration Example Script
+
+Include a short example script under `examples/agent_tool_example.py` demonstrating how an LLM tool loop hooks into `gated_shell()`:
+
+```python
+"""
+Example: Hooking admission-gate into an agent tool execution loop.
+"""
+
+from admission_gate import ActionProposal, gated_shell
+
+
+def agent_shell_tool(command: str, target: str) -> str:
+    proposal = ActionProposal(
+        action_id="agent_call_001",
+        command=command,
+        target_path=target,
+        risk_tier=2,
+    )
+
+    executed, output, code = gated_shell(
+        proposal,
+        allowed_roots=["./workspace"],
+        log_path="audit_log.jsonl",
+        require_confirm=True,
+    )
+
+    if not executed:
+        return f"Refused by gate: {output}"
+
+    return f"Success (exit code {code}):\n{output}"
+
+
+if __name__ == "__main__":
+    result = agent_shell_tool("ls -la", "./workspace")
+    print(result)
+
+
+
+
+# 1. Create the issue template directory and file
+mkdir -p .github/ISSUE_TEMPLATE
+cat << 'EOF' > .github/ISSUE_TEMPLATE/path_bypass.md
+---
+name: Path bypass / policy edge case
+about: Report a path canonicalization escape or policy engine loophole
+title: "[BYPASS]: "
+labels: bug, security
+---
+
+### Environment
+- OS: [e.g. Windows 11, macOS Sonoma, Ubuntu 24.04, Android Termux]
+- Python Version: [e.g. 3.11]
+
+### Proposed Action
+```json
+{
+  "action_id": "test_bypass",
+  "command": "...",
+  "target_path": "...",
+  "risk_tier": 1
+}
+
+
+
+# admission-gate
+
+A lightweight admission gatekeeper and cryptographic audit logger for autonomous CLI agents.
+
+When local scripts or LLMs execute commands in a subshell, developers are forced between two extremes: fully autonomous execution that risks destructive operations, or prompt fatigue from micro-approving dozens of benign commands. `admission-gate` sits between the agent and your shell:
+
+1. **Deterministic Filter**: Blocks dangerous patterns (`rm -rf /`) and restricts filesystem access to configured `allowed_roots` using strict path canonicalization.
+2. **Interactive TTY Confirmation**: Halts for human authorization (`[y/N]`) only on proposals that pass static policy checks.
+3. **SHA-256 Audit Trail**: Commits all proposals, policy outcomes, and approval decisions to an append-only, hash-chained log.
+
+Requires Python 3.8+ with zero third-party dependencies.
+
+---
+
+## Quickstart
+
+```bash
+git clone [https://github.com/ak-skwaa-mahawk/admission-gate.git](https://github.com/ak-skwaa-mahawk/admission-gate.git)
+cd admission-gate
+pip install .
+```
+
+---
+
+## Library Usage
+
+Wrap your agent's shell execution tool so rejected actions never hit the subshell:
+
+```python
+from admission_gate import ActionProposal, gated_shell
+
+proposal = ActionProposal(
+    action_id="task_101",
+    command="rm scratch.tmp",
+    target_path="./workspace/scratch.tmp",
+    risk_tier=2,
+)
+
+# Returns (executed: bool, output: str, exit_code: int)
+executed, output, code = gated_shell(
+    proposal,
+    allowed_roots=["./workspace"],
+    log_path="audit_log.jsonl",
+    require_confirm=True,
+)
+
+if not executed:
+    print(f"Action refused: {output}")
+else:
+    print(f"Command succeeded:\n{output}")
+```
+
+### Standalone Policy Checks
+
+```python
+from admission_gate import ActionProposal, evaluate
+
+p = ActionProposal("chk_1", "cat /etc/shadow", "/etc/shadow", 1)
+passed, reason = evaluate(p)
+# passed -> False
+# reason -> "Blocked: path resolves to protected directory '/etc'"
+```
+
+---
+
+## Verifying Audit Log Integrity
+
+```bash
+python3 src/admission_gate/verify.py audit_log.jsonl
+```
+
+---
+
+## Running Tests
+
+```bash
+PYTHONPATH=src python3 -m unittest discover -s tests
+```
+
+---
+
+## License
+
+[MIT](LICENSE)

admission_gate-0.1.0/pyproject.toml

@@ -0,0 +1,21 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "admission-gate"
+version = "0.1.0"
+description = "Deterministic admission gate with human review and cryptographic audit logging for CLI agents."
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+authors = [{ name = "ak-skwaa-mahawk" }]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+
+[project.scripts]
+admission-gate = "admission_gate.gate:main"
+verify-audit = "admission_gate.verify:main"

admission_gate-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

admission_gate-0.1.0/src/admission_gate/__init__.py

@@ -0,0 +1,13 @@
+"""Deterministic admission gate for CLI agent actions."""
+
+from .gate import ActionProposal, PolicyEngine, AuditLogger, evaluate, gated_shell
+from .verify import verify_log
+
+__all__ = [
+    "ActionProposal",
+    "PolicyEngine",
+    "AuditLogger",
+    "evaluate",
+    "gated_shell",
+    "verify_log",
+]

admission_gate-0.1.0/src/admission_gate/gate.py

@@ -0,0 +1,249 @@
+#!/usr/bin/env python3
+"""
+admission_gate.gate - Library interface and execution wrapper for CLI agent actions.
+"""
+
+import argparse
+import hashlib
+import json
+import os
+import subprocess
+import sys
+import time
+from dataclasses import asdict, dataclass
+from typing import List, Optional, Tuple
+
+
+@dataclass
+class ActionProposal:
+    action_id: str
+    command: str
+    target_path: str
+    risk_tier: int = 1  # 1 = Low, 2 = Medium, 3 = High
+
+
+class PolicyEngine:
+    BLOCKED_PATTERNS = ["rm -rf /", ":(){ :|:& };:", "/dev/sd", "> /dev/null"]
+
+    PROTECTED_PATHS = [
+        "/etc",
+        "/boot",
+        "/sys",
+        "/dev",
+        "/proc",
+        "C:\\Windows",
+        "C:\\Windows\\System32",
+    ]
+
+    @classmethod
+    def _canonicalize(cls, path: str) -> str:
+        expanded = os.path.expanduser(path)
+        if not os.path.exists(expanded):
+            parent = os.path.dirname(expanded) or "."
+            real_parent = os.path.realpath(parent)
+            norm = os.path.join(real_parent, os.path.basename(expanded))
+        else:
+            norm = os.path.realpath(expanded)
+
+        norm = os.path.normcase(norm)
+        if norm.startswith("\\\\?\\"):
+            norm = norm[4:]
+        return os.path.abspath(norm)
+
+    @classmethod
+    def _is_within(cls, child: str, parent: str) -> bool:
+        parent_dir = parent if parent.endswith(os.sep) else parent + os.sep
+        return child == parent or child.startswith(parent_dir)
+
+    @classmethod
+    def evaluate(
+        cls,
+        proposal: ActionProposal,
+        allowed_roots: Optional[List[str]] = None,
+    ) -> Tuple[bool, str]:
+        for pattern in cls.BLOCKED_PATTERNS:
+            if pattern in proposal.command:
+                return False, f"Blocked: matched hazardous pattern '{pattern}'"
+
+        target_norm = cls._canonicalize(proposal.target_path)
+
+        for raw_protected in cls.PROTECTED_PATHS:
+            protected_norm = cls._canonicalize(raw_protected)
+            if cls._is_within(target_norm, protected_norm):
+                return (
+                    False,
+                    f"Blocked: path resolves to protected directory '{raw_protected}'",
+                )
+
+        if allowed_roots:
+            in_allowed = False
+            for raw_allowed in allowed_roots:
+                allowed_norm = cls._canonicalize(raw_allowed)
+                if cls._is_within(target_norm, allowed_norm):
+                    in_allowed = True
+                    break
+            if not in_allowed:
+                allowed_str = ", ".join(allowed_roots)
+                return False, f"Blocked: path escapes allowed roots ({allowed_str})"
+
+        if proposal.risk_tier not in (1, 2, 3):
+            return False, "Blocked: invalid risk tier (must be 1, 2, or 3)"
+
+        return True, "Passed automated policy checks."
+
+
+class AuditLogger:
+    def __init__(self, log_path: str = "audit_log.jsonl"):
+        self.log_path = log_path
+        self.last_hash = self._recover_tip_hash()
+
+    def _recover_tip_hash(self) -> str:
+        if not os.path.exists(self.log_path):
+            return "0" * 64
+        last_line = ""
+        with open(self.log_path, "r", encoding="utf-8") as f:
+            for line in f:
+                if line.strip():
+                    last_line = line
+        if not last_line:
+            return "0" * 64
+        try:
+            return json.loads(last_line).get("entry_hash", "0" * 64)
+        except json.JSONDecodeError:
+            return "0" * 64
+
+    def commit(
+        self,
+        proposal: ActionProposal,
+        passed: bool,
+        reason: str,
+        human_decision: Optional[bool],
+    ) -> str:
+        payload = {
+            "prev_hash": self.last_hash,
+            "timestamp_ns": time.time_ns(),
+            "proposal": asdict(proposal),
+            "policy_passed": passed,
+            "policy_reason": reason,
+            "human_accepted": human_decision,
+        }
+        serialized = json.dumps(payload, sort_keys=True)
+        entry_hash = hashlib.sha256(serialized.encode("utf-8")).hexdigest()
+        record = {**payload, "entry_hash": entry_hash}
+
+        with open(self.log_path, "a", encoding="utf-8") as f:
+            f.write(json.dumps(record) + "\n")
+
+        self.last_hash = entry_hash
+        return entry_hash
+
+
+def _prompt_tty(message: str) -> bool:
+    try:
+        tty_path = "CON:" if os.name == "nt" else "/dev/tty"
+        with open(tty_path, "r") as t_in, open(tty_path, "w") as t_out:
+            t_out.write(message)
+            t_out.flush()
+            res = t_in.readline().strip().lower()
+            return res in ("y", "yes")
+    except (OSError, IOError):
+        return False
+
+
+def evaluate(
+    proposal: ActionProposal, allowed_roots: Optional[List[str]] = None
+) -> Tuple[bool, str]:
+    return PolicyEngine.evaluate(proposal, allowed_roots=allowed_roots)
+
+
+def gated_shell(
+    proposal: ActionProposal,
+    allowed_roots: Optional[List[str]] = None,
+    log_path: str = "audit_log.jsonl",
+    require_confirm: bool = True,
+) -> Tuple[bool, str, int]:
+    logger = AuditLogger(log_path=log_path)
+    passed, reason = evaluate(proposal, allowed_roots=allowed_roots)
+
+    decision = None
+    if passed:
+        if require_confirm:
+            msg = f"[Agent Gate] Authorize command '{proposal.command}' on target '{proposal.target_path}'? [y/N]: "
+            decision = _prompt_tty(msg)
+        else:
+            decision = True
+    else:
+        decision = False
+
+    logger.commit(proposal, passed, reason, decision)
+
+    if not (passed and decision):
+        err_msg = reason if not passed else "Execution rejected by operator."
+        return False, err_msg, -1
+
+    res = subprocess.run(
+        proposal.command,
+        shell=True,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        text=True,
+    )
+    output = res.stdout if res.returncode == 0 else res.stderr
+    return True, output, res.returncode
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Deterministic admission gate for CLI agent actions."
+    )
+    parser.add_argument(
+        "--allow-root",
+        action="append",
+        dest="allowed_roots",
+        help="Allowed filesystem boundary (can be specified multiple times)",
+    )
+    parser.add_argument(
+        "--log-file",
+        default="audit_log.jsonl",
+        help="Path to write the audit trail (default: audit_log.jsonl)",
+    )
+    parser.add_argument(
+        "--no-confirm",
+        action="store_true",
+        help="Bypass interactive TTY confirmation (policy checks still enforced)",
+    )
+    args = parser.parse_args()
+
+    logger = AuditLogger(log_path=args.log_file)
+    print(f"[Agent Gate] Online. Log: {args.log_file} (Tip: {logger.last_hash[:16]}...)")
+
+    if not sys.stdin.isatty():
+        for line in sys.stdin:
+            raw = line.strip()
+            if not raw:
+                continue
+            try:
+                data = json.loads(raw)
+                proposal = ActionProposal(
+                    action_id=str(data["action_id"]),
+                    command=str(data["command"]),
+                    target_path=str(data["target_path"]),
+                    risk_tier=int(data.get("risk_tier", 1)),
+                )
+                executed, out, code = gated_shell(
+                    proposal,
+                    allowed_roots=args.allowed_roots,
+                    log_path=args.log_file,
+                    require_confirm=not args.no_confirm,
+                )
+                status = f"Code {code}" if executed else "Blocked"
+                print(f"Result [{proposal.action_id}]: {status} - {out.strip()}")
+            except Exception as e:
+                print(f"Error parsing line: {e}", file=sys.stderr)
+    else:
+        print("Reading stdin for JSON proposals. Example:")
+        print('{"action_id": "1", "command": "echo test", "target_path": "./workspace", "risk_tier": 1}')
+
+
+if __name__ == "__main__":
+    main()

admission_gate-0.1.0/src/admission_gate/verify.py

@@ -0,0 +1,74 @@
+#!/usr/bin/env python3
+"""Audit log verification CLI."""
+
+import argparse
+import hashlib
+import json
+import sys
+from typing import Tuple
+
+
+def verify_log(log_path: str) -> Tuple[bool, int, str]:
+    expected_prev = "0" * 64
+    count = 0
+
+    with open(log_path, "r", encoding="utf-8") as f:
+        for idx, line in enumerate(f, start=1):
+            raw = line.strip()
+            if not raw:
+                continue
+
+            entry = json.loads(raw)
+            recorded_hash = entry.get("entry_hash")
+
+            if entry.get("prev_hash") != expected_prev:
+                return (
+                    False,
+                    idx,
+                    f"Chain break at line {idx}: expected prev_hash {expected_prev[:16]}, got {entry.get('prev_hash', '')[:16]}",
+                )
+
+            payload = {k: v for k, v in entry.items() if k != "entry_hash"}
+            serialized = json.dumps(payload, sort_keys=True)
+            recalculated = hashlib.sha256(serialized.encode("utf-8")).hexdigest()
+
+            if recorded_hash != recalculated:
+                return (
+                    False,
+                    idx,
+                    f"Tamper detected at line {idx}: hash mismatch",
+                )
+
+            expected_prev = recorded_hash
+            count += 1
+
+    return True, count, expected_prev
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Verify SHA-256 hash-chain integrity of an admission-gate audit log."
+    )
+    parser.add_argument(
+        "log_path",
+        nargs="?",
+        default="audit_log.jsonl",
+        help="Path to the audit log JSONL file (default: audit_log.jsonl)",
+    )
+    args = parser.parse_args()
+
+    try:
+        ok, count, detail = verify_log(args.log_path)
+        if ok:
+            print(f"[PASS] Audit log intact. Verified {count} records. Tip: {detail[:16]}...")
+            sys.exit(0)
+        else:
+            print(f"[FAIL] {detail}", file=sys.stderr)
+            sys.exit(1)
+    except FileNotFoundError:
+        print(f"[ERROR] Log file not found: {args.log_path}", file=sys.stderr)
+        sys.exit(2)
+
+
+if __name__ == "__main__":
+    main()

admission_gate-0.1.0/src/admission_gate.egg-info/PKG-INFO

@@ -0,0 +1,194 @@
+Metadata-Version: 2.4
+Name: admission-gate
+Version: 0.1.0
+Summary: Deterministic admission gate with human review and cryptographic audit logging for CLI agents.
+Author: ak-skwaa-mahawk
+License: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# admission-gate
+
+[![CI](https://github.com/ak-skwaa-mahawk/admission-gate/actions/workflows/ci.yml/badge.svg)](https://github.com/ak-skwaa-mahawk/admission-gate/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Release](https://img.shields.io/github/v/release/ak-skwaa-mahawk/admission-gate)](https://github.com/ak-skwaa-mahawk/admission-gate/releases)
+
+A lightweight admission gatekeeper and cryptographic audit logger for autonomous CLI agents.
+
+---
+name: Path bypass / policy edge case
+about: Report a path canonicalization escape or policy engine loophole
+title: "[BYPASS]: "
+labels: bug, security
+---
+
+### Environment
+- OS: [e.g. Windows 11, macOS Sonoma, Ubuntu 24.04, Android Termux]
+- Python Version: [e.g. 3.11]
+
+### Proposed Action
+```json
+{
+  "action_id": "test_bypass",
+  "command": "...",
+  "target_path": "...",
+  "risk_tier": 1
+}
+
+
+---
+
+### 3. Add an Integration Example Script
+
+Include a short example script under `examples/agent_tool_example.py` demonstrating how an LLM tool loop hooks into `gated_shell()`:
+
+```python
+"""
+Example: Hooking admission-gate into an agent tool execution loop.
+"""
+
+from admission_gate import ActionProposal, gated_shell
+
+
+def agent_shell_tool(command: str, target: str) -> str:
+    proposal = ActionProposal(
+        action_id="agent_call_001",
+        command=command,
+        target_path=target,
+        risk_tier=2,
+    )
+
+    executed, output, code = gated_shell(
+        proposal,
+        allowed_roots=["./workspace"],
+        log_path="audit_log.jsonl",
+        require_confirm=True,
+    )
+
+    if not executed:
+        return f"Refused by gate: {output}"
+
+    return f"Success (exit code {code}):\n{output}"
+
+
+if __name__ == "__main__":
+    result = agent_shell_tool("ls -la", "./workspace")
+    print(result)
+
+
+
+
+# 1. Create the issue template directory and file
+mkdir -p .github/ISSUE_TEMPLATE
+cat << 'EOF' > .github/ISSUE_TEMPLATE/path_bypass.md
+---
+name: Path bypass / policy edge case
+about: Report a path canonicalization escape or policy engine loophole
+title: "[BYPASS]: "
+labels: bug, security
+---
+
+### Environment
+- OS: [e.g. Windows 11, macOS Sonoma, Ubuntu 24.04, Android Termux]
+- Python Version: [e.g. 3.11]
+
+### Proposed Action
+```json
+{
+  "action_id": "test_bypass",
+  "command": "...",
+  "target_path": "...",
+  "risk_tier": 1
+}
+
+
+
+# admission-gate
+
+A lightweight admission gatekeeper and cryptographic audit logger for autonomous CLI agents.
+
+When local scripts or LLMs execute commands in a subshell, developers are forced between two extremes: fully autonomous execution that risks destructive operations, or prompt fatigue from micro-approving dozens of benign commands. `admission-gate` sits between the agent and your shell:
+
+1. **Deterministic Filter**: Blocks dangerous patterns (`rm -rf /`) and restricts filesystem access to configured `allowed_roots` using strict path canonicalization.
+2. **Interactive TTY Confirmation**: Halts for human authorization (`[y/N]`) only on proposals that pass static policy checks.
+3. **SHA-256 Audit Trail**: Commits all proposals, policy outcomes, and approval decisions to an append-only, hash-chained log.
+
+Requires Python 3.8+ with zero third-party dependencies.
+
+---
+
+## Quickstart
+
+```bash
+git clone [https://github.com/ak-skwaa-mahawk/admission-gate.git](https://github.com/ak-skwaa-mahawk/admission-gate.git)
+cd admission-gate
+pip install .
+```
+
+---
+
+## Library Usage
+
+Wrap your agent's shell execution tool so rejected actions never hit the subshell:
+
+```python
+from admission_gate import ActionProposal, gated_shell
+
+proposal = ActionProposal(
+    action_id="task_101",
+    command="rm scratch.tmp",
+    target_path="./workspace/scratch.tmp",
+    risk_tier=2,
+)
+
+# Returns (executed: bool, output: str, exit_code: int)
+executed, output, code = gated_shell(
+    proposal,
+    allowed_roots=["./workspace"],
+    log_path="audit_log.jsonl",
+    require_confirm=True,
+)
+
+if not executed:
+    print(f"Action refused: {output}")
+else:
+    print(f"Command succeeded:\n{output}")
+```
+
+### Standalone Policy Checks
+
+```python
+from admission_gate import ActionProposal, evaluate
+
+p = ActionProposal("chk_1", "cat /etc/shadow", "/etc/shadow", 1)
+passed, reason = evaluate(p)
+# passed -> False
+# reason -> "Blocked: path resolves to protected directory '/etc'"
+```
+
+---
+
+## Verifying Audit Log Integrity
+
+```bash
+python3 src/admission_gate/verify.py audit_log.jsonl
+```
+
+---
+
+## Running Tests
+
+```bash
+PYTHONPATH=src python3 -m unittest discover -s tests
+```
+
+---
+
+## License
+
+[MIT](LICENSE)

admission_gate-0.1.0/src/admission_gate.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+LICENSE
+README.md
+pyproject.toml
+src/admission_gate/__init__.py
+src/admission_gate/gate.py
+src/admission_gate/verify.py
+src/admission_gate.egg-info/PKG-INFO
+src/admission_gate.egg-info/SOURCES.txt
+src/admission_gate.egg-info/dependency_links.txt
+src/admission_gate.egg-info/entry_points.txt
+src/admission_gate.egg-info/top_level.txt
+tests/test_gate.py

admission_gate-0.1.0/src/admission_gate.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

admission_gate-0.1.0/src/admission_gate.egg-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+admission-gate = admission_gate.gate:main
+verify-audit = admission_gate.verify:main

admission_gate-0.1.0/src/admission_gate.egg-info/top_level.txt

@@ -0,0 +1 @@
+admission_gate

admission_gate-0.1.0/tests/test_gate.py

@@ -0,0 +1,55 @@
+import os
+import tempfile
+import unittest
+from admission_gate.gate import ActionProposal, PolicyEngine, AuditLogger, evaluate
+from admission_gate.verify import verify_log
+
+
+class TestPolicyEngine(unittest.TestCase):
+    def test_blocks_dangerous_commands(self):
+        p = ActionProposal("1", "rm -rf /", "./workspace", 1)
+        passed, _ = evaluate(p)
+        self.assertFalse(passed)
+
+    def test_blocks_protected_directories(self):
+        p = ActionProposal("2", "touch /etc/config", "/etc/config", 1)
+        passed, _ = evaluate(p)
+        self.assertFalse(passed)
+
+    def test_enforces_allowed_roots(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            allowed = os.path.join(tmp, "allowed")
+            os.makedirs(allowed, exist_ok=True)
+
+            good_p = ActionProposal("3", "touch test", os.path.join(allowed, "file.txt"), 1)
+            passed, _ = evaluate(good_p, allowed_roots=[allowed])
+            self.assertTrue(passed)
+
+            bad_p = ActionProposal("4", "touch test", os.path.join(tmp, "outside.txt"), 1)
+            passed, _ = evaluate(bad_p, allowed_roots=[allowed])
+            self.assertFalse(passed)
+
+
+class TestAuditChain(unittest.TestCase):
+    def test_log_and_verification(self):
+        with tempfile.NamedTemporaryFile(suffix=".jsonl", delete=False) as f:
+            log_path = f.name
+
+        try:
+            logger = AuditLogger(log_path=log_path)
+            p1 = ActionProposal("1", "echo hi", "./workspace", 1)
+            p2 = ActionProposal("2", "ls", "./workspace", 1)
+
+            logger.commit(p1, True, "passed", True)
+            logger.commit(p2, True, "passed", False)
+
+            ok, count, _ = verify_log(log_path)
+            self.assertTrue(ok)
+            self.assertEqual(count, 2)
+        finally:
+            if os.path.exists(log_path):
+                os.remove(log_path)
+
+
+if __name__ == "__main__":
+    unittest.main()