pudicus 0.1.1__tar.gz

pudicus-0.1.1/PKG-INFO

@@ -0,0 +1,145 @@
+Metadata-Version: 2.4
+Name: pudicus
+Version: 0.1.1
+Summary: A pluggable inspection gate for Git commits
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: PyYAML
+Requires-Dist: behave
+
+# Pudicus
+
+Pudicus ("modest, chaste, keeping pure") is a standalone, pluggable inspection gate for Git commits. 
+
+It was built to **shift left** the problem of secrets and confidential information leaking into source code. While it is technically possible to rewrite git history later (e.g., using `git filter-repo`) to scrub leaked keys, it is vastly better to catch the information *before* it ever gets committed to the local repository in the first place.
+
+In the era of agentic coding, a specific problem arises: **How do we ensure that autonomous AI agents (or hurried humans) actually run the necessary security checks before committing code?**
+
+Pudicus bridges the gap between agent automation and deployment safety by acting like an **agricultural inspector's produce sticker**. It intercepts and blocks secrets at the staging area, generating a cryptographically verifiable receipt proving the code was scanned. A downstream deploy gate then prevents the truck from unloading if the stickers are missing.
+
+```mermaid
+flowchart LR
+    Agent["Agent / Developer"] -->|Writes Code| Hook["Pudicus Git Hook"]
+    
+    subgraph Pudicus Validation
+        Hook -->|Runs| Scanners["Scanners<br/>(Gitleaks, Tactus, etc.)"]
+        Scanners -->|Clean| Sig["Cryptographic Signature<br/>(HMAC-SHA256)"]
+        Scanners -->|Issues Found| Block["Commit Blocked"]
+    end
+    
+    Sig --> Commit["Signed Commit"]
+    
+    Agent -.->|Bypasses hook| Unsigned["Unsigned Commit"]
+    
+    Commit --> Gate{"Deploy Gate<br/>(CI/CD)"}
+    Unsigned -.-> Gate
+    
+    Gate -->|Valid Signature| Prod[("(Production)")]
+    Gate -->|No Signature| Reject["Deploy Rejected"]
+    
+    style Prod fill:#ccffcc,stroke:#00aa00
+    style Reject fill:#ffcccc,stroke:#ff0000
+```
+
+Because the agent does not have access to the cryptographic secret required to mint the signature, the absolute easiest path for an agent to get its code deployed is to simply let the hook run the scanners.
+
+---
+
+## Quick Start
+
+Pudicus is built in Python and requires `git` on the host machine.
+
+**1. Install the CLI:**
+```bash
+pip install pudicus
+```
+*(Note: Until published to PyPI, use `pip install git+ssh://git@github.com/AnthusAI/Pudicus.git`)*
+
+**2. Initialize a repository:**
+Run this in your target repository. It generates the shared secret and installs the `.git/hooks/commit-msg` hook.
+```bash
+cd my-repo
+pudicus install
+```
+
+**3. Configure your scanners:**
+Create a `.pudicus.yml` file in the root of your repository to define what must pass before a commit is signed:
+```yaml
+version: 1
+checkers:
+  - name: gitleaks
+    type: command
+    command: gitleaks protect --staged
+    success_codes: [0]
+```
+
+**4. Add the deploy gate to CI/CD:**
+In your deployment pipeline (e.g., GitHub Actions), verify the incoming commits:
+```bash
+pudicus verify HEAD~5..HEAD
+```
+
+---
+
+## Custom Agent-Based Scanning (Tactus)
+
+While standard tools like Gitleaks are great for finding AWS IAM keys, they struggle with subtle, context-dependent leaks—like mentioning a confidential client's name or proprietary business logic. 
+
+Pudicus natively supports **Tactus procedures** for agent-based code review. 
+
+### Example: Protecting Confidential Client Names
+Imagine you have a list of highly confidential clients that should never be mentioned in your repository's source code. 
+
+1. Create a `.gitignored` file named `confidential_clients.txt`.
+2. Write a Tactus procedure (e.g., `check_clients`) that reads `confidential_clients.txt` and scans the staged files to ensure none of those names appear.
+3. Add the procedure to your `.pudicus.yml`:
+
+```yaml
+version: 1
+checkers:
+  - name: tactus-confidentiality-scan
+    type: tactus
+    procedure: check_clients
+```
+
+When a commit is made, Pudicus will invoke Tactus. If Tactus finds a leaked client name, it exits with an error, Pudicus blocks the commit, and prompts a human for an override password. If the code is clean, the signature is minted and the commit proceeds.
+
+---
+
+## Deep Dive: How it works
+
+### 1. The Commit Hook
+Instead of forcing complex asymmetric cryptography on developers, Pudicus uses a simple shared HMAC secret. 
+
+When a commit is created, Pudicus intercepts it:
+1. It computes the hash of the git tree (the actual code).
+2. It runs the scanners against that tree.
+3. If clean, it generates an HMAC signature and appends it to the commit message as Git trailers.
+
+```text
+Inspected-by: pudicus-v1
+Inspection-tree: f18588e0c5f5b0a5ba281b5a78242127919d2388
+Inspection-result: clean
+Inspection-at: 2026-08-31T17:01:34Z
+Inspection-sig: hmac-sha256:8cce6e3714782d025eb4ec4aec755...
+```
+
+### 2. Retroactive Approval (Signature Pooling)
+Because Git commit hashes change if you modify a commit message, you cannot simply add signatures to old commits without rewriting history (e.g., `git rebase`). 
+
+To solve this, Pudicus ties the signature to the **Tree Hash** (the codebase state) rather than the **Commit Hash**. 
+
+If an agent bypasses the hook with `--no-verify`, or if you are onboarding an older project, you can run `pudicus approve`. This creates an empty "paperwork" commit at the tip of your branch that holds the signatures for the older commits.
+
+```mermaid
+flowchart LR
+    C1["Commit 1<br/>Tree: A<br/>Signed: Yes"] --> C2["Commit 2<br/>Tree: B<br/>Signed: No"]
+    C2 --> C3["Commit 3<br/>Tree: C<br/>Signed: No"]
+    C3 --> AC["Approval Commit<br/>Signs Trees: B, C"]
+    
+    AC --> Gate{"Deploy Gate<br/>pudicus verify"}
+    Gate -->|Pools valid signatures| Check["Are Trees A, B, and C in the pool?"]
+    Check -->|Yes| Deploy["Deploy Success"]
+```
+
+This provides a clean escape hatch that achieves full compliance without destroying Git history.

pudicus-0.1.1/README.md

@@ -0,0 +1,136 @@
+# Pudicus
+
+Pudicus ("modest, chaste, keeping pure") is a standalone, pluggable inspection gate for Git commits. 
+
+It was built to **shift left** the problem of secrets and confidential information leaking into source code. While it is technically possible to rewrite git history later (e.g., using `git filter-repo`) to scrub leaked keys, it is vastly better to catch the information *before* it ever gets committed to the local repository in the first place.
+
+In the era of agentic coding, a specific problem arises: **How do we ensure that autonomous AI agents (or hurried humans) actually run the necessary security checks before committing code?**
+
+Pudicus bridges the gap between agent automation and deployment safety by acting like an **agricultural inspector's produce sticker**. It intercepts and blocks secrets at the staging area, generating a cryptographically verifiable receipt proving the code was scanned. A downstream deploy gate then prevents the truck from unloading if the stickers are missing.
+
+```mermaid
+flowchart LR
+    Agent["Agent / Developer"] -->|Writes Code| Hook["Pudicus Git Hook"]
+    
+    subgraph Pudicus Validation
+        Hook -->|Runs| Scanners["Scanners<br/>(Gitleaks, Tactus, etc.)"]
+        Scanners -->|Clean| Sig["Cryptographic Signature<br/>(HMAC-SHA256)"]
+        Scanners -->|Issues Found| Block["Commit Blocked"]
+    end
+    
+    Sig --> Commit["Signed Commit"]
+    
+    Agent -.->|Bypasses hook| Unsigned["Unsigned Commit"]
+    
+    Commit --> Gate{"Deploy Gate<br/>(CI/CD)"}
+    Unsigned -.-> Gate
+    
+    Gate -->|Valid Signature| Prod[("(Production)")]
+    Gate -->|No Signature| Reject["Deploy Rejected"]
+    
+    style Prod fill:#ccffcc,stroke:#00aa00
+    style Reject fill:#ffcccc,stroke:#ff0000
+```
+
+Because the agent does not have access to the cryptographic secret required to mint the signature, the absolute easiest path for an agent to get its code deployed is to simply let the hook run the scanners.
+
+---
+
+## Quick Start
+
+Pudicus is built in Python and requires `git` on the host machine.
+
+**1. Install the CLI:**
+```bash
+pip install pudicus
+```
+*(Note: Until published to PyPI, use `pip install git+ssh://git@github.com/AnthusAI/Pudicus.git`)*
+
+**2. Initialize a repository:**
+Run this in your target repository. It generates the shared secret and installs the `.git/hooks/commit-msg` hook.
+```bash
+cd my-repo
+pudicus install
+```
+
+**3. Configure your scanners:**
+Create a `.pudicus.yml` file in the root of your repository to define what must pass before a commit is signed:
+```yaml
+version: 1
+checkers:
+  - name: gitleaks
+    type: command
+    command: gitleaks protect --staged
+    success_codes: [0]
+```
+
+**4. Add the deploy gate to CI/CD:**
+In your deployment pipeline (e.g., GitHub Actions), verify the incoming commits:
+```bash
+pudicus verify HEAD~5..HEAD
+```
+
+---
+
+## Custom Agent-Based Scanning (Tactus)
+
+While standard tools like Gitleaks are great for finding AWS IAM keys, they struggle with subtle, context-dependent leaks—like mentioning a confidential client's name or proprietary business logic. 
+
+Pudicus natively supports **Tactus procedures** for agent-based code review. 
+
+### Example: Protecting Confidential Client Names
+Imagine you have a list of highly confidential clients that should never be mentioned in your repository's source code. 
+
+1. Create a `.gitignored` file named `confidential_clients.txt`.
+2. Write a Tactus procedure (e.g., `check_clients`) that reads `confidential_clients.txt` and scans the staged files to ensure none of those names appear.
+3. Add the procedure to your `.pudicus.yml`:
+
+```yaml
+version: 1
+checkers:
+  - name: tactus-confidentiality-scan
+    type: tactus
+    procedure: check_clients
+```
+
+When a commit is made, Pudicus will invoke Tactus. If Tactus finds a leaked client name, it exits with an error, Pudicus blocks the commit, and prompts a human for an override password. If the code is clean, the signature is minted and the commit proceeds.
+
+---
+
+## Deep Dive: How it works
+
+### 1. The Commit Hook
+Instead of forcing complex asymmetric cryptography on developers, Pudicus uses a simple shared HMAC secret. 
+
+When a commit is created, Pudicus intercepts it:
+1. It computes the hash of the git tree (the actual code).
+2. It runs the scanners against that tree.
+3. If clean, it generates an HMAC signature and appends it to the commit message as Git trailers.
+
+```text
+Inspected-by: pudicus-v1
+Inspection-tree: f18588e0c5f5b0a5ba281b5a78242127919d2388
+Inspection-result: clean
+Inspection-at: 2026-08-31T17:01:34Z
+Inspection-sig: hmac-sha256:8cce6e3714782d025eb4ec4aec755...
+```
+
+### 2. Retroactive Approval (Signature Pooling)
+Because Git commit hashes change if you modify a commit message, you cannot simply add signatures to old commits without rewriting history (e.g., `git rebase`). 
+
+To solve this, Pudicus ties the signature to the **Tree Hash** (the codebase state) rather than the **Commit Hash**. 
+
+If an agent bypasses the hook with `--no-verify`, or if you are onboarding an older project, you can run `pudicus approve`. This creates an empty "paperwork" commit at the tip of your branch that holds the signatures for the older commits.
+
+```mermaid
+flowchart LR
+    C1["Commit 1<br/>Tree: A<br/>Signed: Yes"] --> C2["Commit 2<br/>Tree: B<br/>Signed: No"]
+    C2 --> C3["Commit 3<br/>Tree: C<br/>Signed: No"]
+    C3 --> AC["Approval Commit<br/>Signs Trees: B, C"]
+    
+    AC --> Gate{"Deploy Gate<br/>pudicus verify"}
+    Gate -->|Pools valid signatures| Check["Are Trees A, B, and C in the pool?"]
+    Check -->|Yes| Deploy["Deploy Success"]
+```
+
+This provides a clean escape hatch that achieves full compliance without destroying Git history.

pudicus-0.1.1/pudicus/cli.py

@@ -0,0 +1,305 @@
+import argparse
+import sys
+import os
+import json
+import subprocess
+from datetime import datetime, timezone
+from pudicus.core import (
+    get_secret, compute_hmac, get_tree_hash, get_commit_tree_hash,
+    load_config, execute_checkers, get_trailer, run_cmd, SECRET_FILE_DEFAULT
+)
+
+def print_info(msg):
+    print(f"\033[1;34m[pudicus]\033[0m {msg}", file=sys.stderr)
+
+def print_warn(msg):
+    print(f"\033[1;33m[pudicus]\033[0m {msg}", file=sys.stderr)
+
+def print_err(msg):
+    print(f"\033[1;31m[pudicus ERROR]\033[0m {msg}", file=sys.stderr)
+
+def cmd_install(args):
+    """Setup the git hook and secret."""
+    repo_root = run_cmd(["git", "rev-parse", "--show-toplevel"]).stdout.strip()
+    hook_path = os.path.join(repo_root, ".git", "hooks", "commit-msg")
+    
+    if os.path.exists(hook_path):
+        print_warn(f"Hook already exists at {hook_path}. Overwrite? [y/N]")
+        if input().lower() != 'y':
+            print_info("Skipped hook installation.")
+            return
+
+    # Install the wrapper that calls pudicus hook
+    hook_script = f"""#!/usr/bin/env bash
+# Pudicus commit-msg hook
+pudicus hook "$1"
+"""
+    with open(hook_path, 'w') as f:
+        f.write(hook_script)
+    os.chmod(hook_path, 0o755)
+    print_info(f"Installed git hook at {hook_path}")
+
+    # Generate secret if needed
+    secret_dir = os.path.dirname(SECRET_FILE_DEFAULT)
+    if not os.path.exists(SECRET_FILE_DEFAULT):
+        os.makedirs(secret_dir, exist_ok=True)
+        secret = os.urandom(16).hex()
+        with open(SECRET_FILE_DEFAULT, 'w') as f:
+            f.write(secret)
+        os.chmod(SECRET_FILE_DEFAULT, 0o600)
+        print_info(f"Generated new shared secret at {SECRET_FILE_DEFAULT}")
+    else:
+        print_info(f"Shared secret already exists at {SECRET_FILE_DEFAULT}")
+
+def cmd_hook(args):
+    """Run checkers on staged files and sign the commit."""
+    repo_root = run_cmd(["git", "rev-parse", "--show-toplevel"]).stdout.strip()
+    config = load_config(repo_root)
+    
+    if not config or 'checkers' not in config:
+        print_warn("No .pudicus.yml found or no checkers defined. Skipping inspection.")
+        sys.exit(0)
+    
+    try:
+        secret = get_secret()
+    except FileNotFoundError:
+        print_err("Shared secret not found. Run 'pudicus install' first.")
+        sys.exit(1)
+
+    tree_hash = get_tree_hash()
+    print_info(f"Scanning tree {tree_hash}...")
+    
+    results = execute_checkers(config['checkers'])
+    
+    all_clean = True
+    failed_checkers = []
+    for res in results:
+        if not res.clean:
+            all_clean = False
+            failed_checkers.append(res)
+            
+    validator_str = f"pudicus-v{config.get('version', '1')}"
+    timestamp = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+    
+    if all_clean:
+        result_str = "clean"
+        print_info("✓ All checks passed.")
+    else:
+        print_warn(f"✗ Found issues in {len(failed_checkers)} checker(s):")
+        for res in failed_checkers:
+            print_warn(f"  - {res.name}:")
+            if isinstance(res.findings, list):
+                for f in res.findings:
+                    desc = f.get('Description', 'Unknown')
+                    path = f.get('File', 'Unknown')
+                    print(f"      File: {path} -> {desc}", file=sys.stderr)
+            else:
+                print(f"      {res.findings}", file=sys.stderr)
+                
+        if not sys.stdin.isatty():
+            print_err("Findings require human approval but no interactive terminal is available. Commit blocked.")
+            sys.exit(1)
+            
+        print_warn("Commit will be blocked unless you approve these findings.")
+        password = input(f"\033[1m[pudicus]\033[0m Enter approval passphrase to override: ").strip()
+        
+        if password != secret:
+            print_err("Incorrect passphrase. Commit blocked.")
+            sys.exit(1)
+            
+        result_str = f"override:{len(failed_checkers)}-checkers"
+        print_info("✓ Override approved.")
+
+    hmac_sig = compute_hmac(tree_hash, validator_str, result_str, timestamp, secret)
+    
+    # Append trailers
+    msg_file = args.commit_msg_file
+    with open(msg_file, 'r') as f:
+        msg_content = f.read()
+        
+    proc = subprocess.run(
+        ["git", "interpret-trailers", 
+         f"--trailer=Inspected-by: {validator_str}",
+         f"--trailer=Inspection-tree: {tree_hash}",
+         f"--trailer=Inspection-result: {result_str}",
+         f"--trailer=Inspection-at: {timestamp}",
+         f"--trailer=Inspection-sig: hmac-sha256:{hmac_sig}"],
+        input=msg_content, text=True, capture_output=True, check=True
+    )
+    
+    with open(msg_file, 'w') as f:
+        f.write(proc.stdout)
+        
+    print_info(f"✓ Commit signed: hmac-sha256:{hmac_sig[:16]}...")
+
+def cmd_approve(args):
+    """Retroactively approve commits by generating a paperwork commit."""
+    repo_root = run_cmd(["git", "rev-parse", "--show-toplevel"]).stdout.strip()
+    
+    try:
+        secret = get_secret()
+    except FileNotFoundError:
+        print_err("Shared secret not found. Run 'pudicus install'.")
+        sys.exit(1)
+        
+    range_str = args.range
+    if ".." in range_str:
+        commits = run_cmd(["git", "rev-list", "--reverse", range_str]).stdout.splitlines()
+    else:
+        commits = [run_cmd(["git", "rev-parse", range_str]).stdout.strip()]
+        
+    if not commits:
+        print_info("No commits found in range.")
+        sys.exit(0)
+        
+    config = load_config(repo_root)
+    if not config or 'checkers' not in config:
+        print_err("No .pudicus.yml found.")
+        sys.exit(1)
+        
+    validator_str = f"pudicus-v{config.get('version', '1')}"
+    timestamp = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+    
+    trailers = []
+    
+    for sha in commits:
+        short = sha[:7]
+        print_info(f"Checking commit {short}...")
+        actual_tree = get_commit_tree_hash(sha)
+        
+        # Set up a worktree for the commit
+        import tempfile
+        wt_dir = tempfile.mkdtemp()
+        run_cmd(["git", "worktree", "add", "--detach", wt_dir, sha])
+        
+        try:
+            # We want to scan the diff introduced by this commit, so we soft reset to its parent.
+            parent = run_cmd(["git", "rev-parse", f"{sha}~1"], check=False).stdout.strip()
+            if not parent:
+                # Root commit
+                empty_tree = run_cmd(["git", "hash-object", "-t", "tree", "/dev/null"]).stdout.strip()
+                run_cmd(["git", "reset", "--soft", empty_tree], cwd=wt_dir)
+            else:
+                run_cmd(["git", "reset", "--soft", parent], cwd=wt_dir)
+                
+            results = execute_checkers(config['checkers'], cwd=wt_dir)
+        finally:
+            run_cmd(["git", "worktree", "remove", "-f", wt_dir])
+            
+        all_clean = True
+        failed_checkers = []
+        for res in results:
+            if not res.clean:
+                all_clean = False
+                failed_checkers.append(res)
+                
+        if all_clean:
+            result_str = "clean"
+        else:
+            print_warn(f"✗ Found issues in {short} for {len(failed_checkers)} checker(s).")
+            if not sys.stdin.isatty():
+                print_err("Findings require human approval but no interactive terminal is available. Approval blocked.")
+                sys.exit(1)
+                
+            password = input(f"\033[1m[pudicus]\033[0m Enter approval passphrase to override for {short}: ").strip()
+            if password != secret:
+                print_err("Incorrect passphrase. Approval blocked.")
+                sys.exit(1)
+            result_str = f"override:{len(failed_checkers)}-checkers"
+            
+        hmac_sig = compute_hmac(actual_tree, validator_str, result_str, timestamp, secret)
+        
+        trailers.append(f"--trailer=Inspected-by: {validator_str}")
+        trailers.append(f"--trailer=Inspection-tree: {actual_tree}")
+        trailers.append(f"--trailer=Inspection-result: {result_str}")
+        trailers.append(f"--trailer=Inspection-at: {timestamp}")
+        trailers.append(f"--trailer=Inspection-sig: hmac-sha256:{hmac_sig}")
+        
+    # Create the approval commit
+    commit_msg = "chore: retroactive pudicus approval\n"
+    cmd = ["git", "commit", "--allow-empty", "-F", "-"] + trailers
+    proc = subprocess.run(cmd, input=commit_msg, text=True, capture_output=True, check=True)
+    print_info(f"Created approval commit:\n{proc.stdout.strip()}")
+
+def cmd_verify(args):
+    """Verify signatures for a commit range."""
+    try:
+        secret = get_secret()
+    except FileNotFoundError:
+        print_err("Shared secret not found. Run 'pudicus install'.")
+        sys.exit(1)
+        
+    range_str = args.range
+    if ".." in range_str:
+        commits = run_cmd(["git", "rev-list", range_str]).stdout.splitlines()
+    else:
+        commits = [run_cmd(["git", "rev-parse", range_str]).stdout.strip()]
+        
+    # Pool all valid signatures found in the range
+    valid_trees = set()
+    
+    for sha in commits:
+        # Get all trailers from the commit message
+        msg = run_cmd(["git", "log", "-1", sha, "--format=%B"]).stdout
+        # Basic parsing of trailers. git log format for multiple identical keys is tricky,
+        # so we parse the raw message.
+        import re
+        trees = re.findall(r"^Inspection-tree:\s*(.+)$", msg, re.MULTILINE)
+        sigs = re.findall(r"^Inspection-sig:\s*hmac-sha256:(.+)$", msg, re.MULTILINE)
+        validators = re.findall(r"^Inspected-by:\s*(.+)$", msg, re.MULTILINE)
+        results = re.findall(r"^Inspection-result:\s*(.+)$", msg, re.MULTILINE)
+        timestamps = re.findall(r"^Inspection-at:\s*(.+)$", msg, re.MULTILINE)
+        
+        # Zip them up (assuming they appear in blocks)
+        for t, s, v, r, ts in zip(trees, sigs, validators, results, timestamps):
+            expected = compute_hmac(t, v, r, ts, secret)
+            if s == expected:
+                valid_trees.add(t)
+
+    failures = 0
+    for sha in commits:
+        short = sha[:7]
+        actual_tree = get_commit_tree_hash(sha)
+        
+        if actual_tree not in valid_trees:
+            print_err(f"{short}: No valid signature found for tree {actual_tree[:12]}.")
+            failures += 1
+            continue
+            
+        subject = run_cmd(["git", "log", "-1", sha, "--format=%s"]).stdout.strip()[:50]
+        print(f"\033[1;32mPASS:\033[0m {short}: {subject} [verified]")
+        
+    if failures > 0:
+        print_err(f"Verification failed: {failures}/{len(commits)} commit(s) invalid.")
+        sys.exit(1)
+    else:
+        print(f"\033[1;32mAll {len(commits)} commit(s) verified.\033[0m")
+
+def main():
+    parser = argparse.ArgumentParser(description="Pudicus - A pluggable inspection gate for Git commits")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+    
+    install_p = subparsers.add_parser("install", help="Install the commit-msg hook and setup secrets")
+    
+    hook_p = subparsers.add_parser("hook", help="Run checkers (used internally by git hook)")
+    hook_p.add_argument("commit_msg_file", help="Path to the commit message file")
+    
+    verify_p = subparsers.add_parser("verify", help="Verify commits")
+    verify_p.add_argument("range", nargs="?", default="HEAD", help="Commit range (e.g. HEAD~3..HEAD)")
+    
+    approve_p = subparsers.add_parser("approve", help="Retroactively approve commits")
+    approve_p.add_argument("range", help="Commit range to approve")
+    
+    args = parser.parse_args()
+    
+    if args.command == "install":
+        cmd_install(args)
+    elif args.command == "hook":
+        cmd_hook(args)
+    elif args.command == "verify":
+        cmd_verify(args)
+    elif args.command == "approve":
+        cmd_approve(args)
+
+if __name__ == "__main__":
+    main()

pudicus-0.1.1/pudicus/core.py

@@ -0,0 +1,108 @@
+import os
+import sys
+import subprocess
+import hmac
+import hashlib
+import json
+import time
+from datetime import datetime
+from typing import List, Dict, Any, Tuple
+import tempfile
+import yaml
+
+SECRET_FILE_DEFAULT = os.environ.get("PUDICUS_SECRET_PATH", os.path.expanduser("~/.config/pudicus/secret"))
+
+def get_secret(secret_path: str = SECRET_FILE_DEFAULT) -> str:
+    if not os.path.exists(secret_path):
+        raise FileNotFoundError(f"Secret file not found at {secret_path}")
+    with open(secret_path, 'r') as f:
+        return f.read().strip()
+
+def compute_hmac(tree_hash: str, validator: str, result: str, timestamp: str, secret: str) -> str:
+    msg = f"{tree_hash}|{validator}|{result}|{timestamp}".encode('utf-8')
+    return hmac.new(secret.encode('utf-8'), msg, hashlib.sha256).hexdigest()
+
+def run_cmd(cmd: List[str], check: bool = True, capture_output: bool = True, **kwargs) -> subprocess.CompletedProcess:
+    return subprocess.run(cmd, check=check, capture_output=capture_output, text=True, **kwargs)
+
+def get_tree_hash() -> str:
+    return run_cmd(["git", "write-tree"]).stdout.strip()
+
+def get_commit_tree_hash(commit_sha: str) -> str:
+    output = run_cmd(["git", "cat-file", "-p", commit_sha]).stdout
+    for line in output.splitlines():
+        if line.startswith("tree "):
+            return line.split(" ")[1].strip()
+    return ""
+
+def load_config(repo_root: str) -> Dict[str, Any]:
+    config_path = os.path.join(repo_root, ".pudicus.yml")
+    if not os.path.exists(config_path):
+        return {}
+    with open(config_path, 'r') as f:
+        return yaml.safe_load(f) or {}
+
+class CheckerResult:
+    def __init__(self, name: str, clean: bool, findings: Any = None):
+        self.name = name
+        self.clean = clean
+        self.findings = findings
+
+def run_command_checker(checker: Dict[str, Any], cwd: str = None) -> CheckerResult:
+    name = checker.get('name', 'unknown')
+    cmd = checker.get('command', '')
+    success_codes = checker.get('success_codes', [0])
+    
+    # Replace {report_file} if present
+    report_file = None
+    if "{report_file}" in cmd:
+        fd, report_file = tempfile.mkstemp(suffix=".json")
+        os.close(fd)
+        cmd = cmd.replace("{report_file}", report_file)
+    
+    import shlex
+    try:
+        proc = run_cmd(shlex.split(cmd), check=False, capture_output=True, cwd=cwd)
+        is_clean = proc.returncode in success_codes
+        
+        findings = None
+        if not is_clean and report_file and os.path.exists(report_file):
+            try:
+                with open(report_file, 'r') as f:
+                    findings = json.load(f)
+            except Exception:
+                findings = f"Exit code {proc.returncode}\nStdout: {proc.stdout}\nStderr: {proc.stderr}"
+        elif not is_clean:
+            findings = f"Exit code {proc.returncode}\nStdout: {proc.stdout}\nStderr: {proc.stderr}"
+            
+        return CheckerResult(name, is_clean, findings)
+    finally:
+        if report_file and os.path.exists(report_file):
+            os.remove(report_file)
+
+def run_tactus_checker(checker: Dict[str, Any], cwd: str = None) -> CheckerResult:
+    name = checker.get('name', 'tactus-scan')
+    procedure = checker.get('procedure')
+    if not procedure:
+        return CheckerResult(name, False, "No procedure specified for tactus checker")
+    
+    # Mocking tactus invocation based on common patterns
+    cmd = ["tactus", "run", procedure]
+    proc = run_cmd(cmd, check=False, capture_output=True, cwd=cwd)
+    is_clean = proc.returncode == 0
+    return CheckerResult(name, is_clean, proc.stdout if not is_clean else None)
+
+def execute_checkers(checkers: List[Dict[str, Any]], cwd: str = None) -> List[CheckerResult]:
+    results = []
+    for checker in checkers:
+        ctype = checker.get('type', 'command')
+        if ctype == 'command':
+            results.append(run_command_checker(checker, cwd=cwd))
+        elif ctype == 'tactus':
+            results.append(run_tactus_checker(checker, cwd=cwd))
+        else:
+            results.append(CheckerResult(checker.get('name', 'unknown'), False, f"Unknown checker type: {ctype}"))
+    return results
+
+def get_trailer(commit_sha: str, key: str) -> str:
+    return run_cmd(["git", "log", "-1", commit_sha, f"--format=%(trailers:key={key},valueonly)"]).stdout.strip()

pudicus-0.1.1/pudicus.egg-info/PKG-INFO

@@ -0,0 +1,145 @@
+Metadata-Version: 2.4
+Name: pudicus
+Version: 0.1.1
+Summary: A pluggable inspection gate for Git commits
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: PyYAML
+Requires-Dist: behave
+
+# Pudicus
+
+Pudicus ("modest, chaste, keeping pure") is a standalone, pluggable inspection gate for Git commits. 
+
+It was built to **shift left** the problem of secrets and confidential information leaking into source code. While it is technically possible to rewrite git history later (e.g., using `git filter-repo`) to scrub leaked keys, it is vastly better to catch the information *before* it ever gets committed to the local repository in the first place.
+
+In the era of agentic coding, a specific problem arises: **How do we ensure that autonomous AI agents (or hurried humans) actually run the necessary security checks before committing code?**
+
+Pudicus bridges the gap between agent automation and deployment safety by acting like an **agricultural inspector's produce sticker**. It intercepts and blocks secrets at the staging area, generating a cryptographically verifiable receipt proving the code was scanned. A downstream deploy gate then prevents the truck from unloading if the stickers are missing.
+
+```mermaid
+flowchart LR
+    Agent["Agent / Developer"] -->|Writes Code| Hook["Pudicus Git Hook"]
+    
+    subgraph Pudicus Validation
+        Hook -->|Runs| Scanners["Scanners<br/>(Gitleaks, Tactus, etc.)"]
+        Scanners -->|Clean| Sig["Cryptographic Signature<br/>(HMAC-SHA256)"]
+        Scanners -->|Issues Found| Block["Commit Blocked"]
+    end
+    
+    Sig --> Commit["Signed Commit"]
+    
+    Agent -.->|Bypasses hook| Unsigned["Unsigned Commit"]
+    
+    Commit --> Gate{"Deploy Gate<br/>(CI/CD)"}
+    Unsigned -.-> Gate
+    
+    Gate -->|Valid Signature| Prod[("(Production)")]
+    Gate -->|No Signature| Reject["Deploy Rejected"]
+    
+    style Prod fill:#ccffcc,stroke:#00aa00
+    style Reject fill:#ffcccc,stroke:#ff0000
+```
+
+Because the agent does not have access to the cryptographic secret required to mint the signature, the absolute easiest path for an agent to get its code deployed is to simply let the hook run the scanners.
+
+---
+
+## Quick Start
+
+Pudicus is built in Python and requires `git` on the host machine.
+
+**1. Install the CLI:**
+```bash
+pip install pudicus
+```
+*(Note: Until published to PyPI, use `pip install git+ssh://git@github.com/AnthusAI/Pudicus.git`)*
+
+**2. Initialize a repository:**
+Run this in your target repository. It generates the shared secret and installs the `.git/hooks/commit-msg` hook.
+```bash
+cd my-repo
+pudicus install
+```
+
+**3. Configure your scanners:**
+Create a `.pudicus.yml` file in the root of your repository to define what must pass before a commit is signed:
+```yaml
+version: 1
+checkers:
+  - name: gitleaks
+    type: command
+    command: gitleaks protect --staged
+    success_codes: [0]
+```
+
+**4. Add the deploy gate to CI/CD:**
+In your deployment pipeline (e.g., GitHub Actions), verify the incoming commits:
+```bash
+pudicus verify HEAD~5..HEAD
+```
+
+---
+
+## Custom Agent-Based Scanning (Tactus)
+
+While standard tools like Gitleaks are great for finding AWS IAM keys, they struggle with subtle, context-dependent leaks—like mentioning a confidential client's name or proprietary business logic. 
+
+Pudicus natively supports **Tactus procedures** for agent-based code review. 
+
+### Example: Protecting Confidential Client Names
+Imagine you have a list of highly confidential clients that should never be mentioned in your repository's source code. 
+
+1. Create a `.gitignored` file named `confidential_clients.txt`.
+2. Write a Tactus procedure (e.g., `check_clients`) that reads `confidential_clients.txt` and scans the staged files to ensure none of those names appear.
+3. Add the procedure to your `.pudicus.yml`:
+
+```yaml
+version: 1
+checkers:
+  - name: tactus-confidentiality-scan
+    type: tactus
+    procedure: check_clients
+```
+
+When a commit is made, Pudicus will invoke Tactus. If Tactus finds a leaked client name, it exits with an error, Pudicus blocks the commit, and prompts a human for an override password. If the code is clean, the signature is minted and the commit proceeds.
+
+---
+
+## Deep Dive: How it works
+
+### 1. The Commit Hook
+Instead of forcing complex asymmetric cryptography on developers, Pudicus uses a simple shared HMAC secret. 
+
+When a commit is created, Pudicus intercepts it:
+1. It computes the hash of the git tree (the actual code).
+2. It runs the scanners against that tree.
+3. If clean, it generates an HMAC signature and appends it to the commit message as Git trailers.
+
+```text
+Inspected-by: pudicus-v1
+Inspection-tree: f18588e0c5f5b0a5ba281b5a78242127919d2388
+Inspection-result: clean
+Inspection-at: 2026-08-31T17:01:34Z
+Inspection-sig: hmac-sha256:8cce6e3714782d025eb4ec4aec755...
+```
+
+### 2. Retroactive Approval (Signature Pooling)
+Because Git commit hashes change if you modify a commit message, you cannot simply add signatures to old commits without rewriting history (e.g., `git rebase`). 
+
+To solve this, Pudicus ties the signature to the **Tree Hash** (the codebase state) rather than the **Commit Hash**. 
+
+If an agent bypasses the hook with `--no-verify`, or if you are onboarding an older project, you can run `pudicus approve`. This creates an empty "paperwork" commit at the tip of your branch that holds the signatures for the older commits.
+
+```mermaid
+flowchart LR
+    C1["Commit 1<br/>Tree: A<br/>Signed: Yes"] --> C2["Commit 2<br/>Tree: B<br/>Signed: No"]
+    C2 --> C3["Commit 3<br/>Tree: C<br/>Signed: No"]
+    C3 --> AC["Approval Commit<br/>Signs Trees: B, C"]
+    
+    AC --> Gate{"Deploy Gate<br/>pudicus verify"}
+    Gate -->|Pools valid signatures| Check["Are Trees A, B, and C in the pool?"]
+    Check -->|Yes| Deploy["Deploy Success"]
+```
+
+This provides a clean escape hatch that achieves full compliance without destroying Git history.

pudicus-0.1.1/pudicus.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+README.md
+pyproject.toml
+pudicus/__init__.py
+pudicus/cli.py
+pudicus/core.py
+pudicus.egg-info/PKG-INFO
+pudicus.egg-info/SOURCES.txt
+pudicus.egg-info/dependency_links.txt
+pudicus.egg-info/entry_points.txt
+pudicus.egg-info/requires.txt
+pudicus.egg-info/top_level.txt

pudicus-0.1.1/pudicus.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

pudicus-0.1.1/pudicus.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pudicus = pudicus.cli:main

pudicus-0.1.1/pudicus.egg-info/requires.txt

@@ -0,0 +1,2 @@
+PyYAML
+behave

pudicus-0.1.1/pudicus.egg-info/top_level.txt

@@ -0,0 +1 @@
+pudicus

pudicus-0.1.1/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["setuptools>=42"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pudicus"
+version = "0.1.1"
+description = "A pluggable inspection gate for Git commits"
+readme = "README.md"
+requires-python = ">=3.8"
+dependencies = [
+    "PyYAML",
+    "behave",
+]
+
+[tool.setuptools]
+packages = ["pudicus"]
+
+[project.scripts]
+pudicus = "pudicus.cli:main"
+
+[tool.semantic_release]
+version_toml = ["pyproject.toml:project.version"]
+branch = "main"
+upload_to_pypi = true
+upload_to_release = true
+build_command = "python -m pip install build && python -m build"

pudicus-0.1.1/setup.cfg

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