AuditWalk

Local-first security + audit toolkit to capture evidence from the browser, queue it for review, and run lightweight integrity scans without leaving your machine.

Build Planning

• Master MVP checklist: docs/MVP_BUILD_DOCUMENTATION.md
• Execution roadmap: docs/ROADMAP.md
• Near-term task list: TODO.md
• Module ownership map: docs/architecture/module_ownership.md

Quick Start (Developer Setup)

Clone the repository and run the initial setup:

make install-dev
make hooks
make repo-steward-check

This will:

• Install development dependencies into the local virtual environment
• Install the repository pre-commit hook
• Verify repository stewardship checks pass

Developer setup

Install the local git pre-commit hook:

make hooks

Check whether it is installed:

make hooks-status

MVP Scope

• Bookmarklet that POSTs the active tab (URL + title + timestamp) to a localhost ingest endpoint.
• Loopback-only ingest server (scripts/run_ingest.py) that validates payloads and appends them to ~/.auditwalk/inbox.jsonl.
• Inbox utilities + CLI commands (scripts/auditwalk_cli.py) for listing, processing, and manually adding queue entries.
• Hardened file-system scanner (scanner.py) with optional hashing, suspicious-extension detection, and JSON export to feed future analysis steps.
• Documentation covering install, security notes, and usage so Antoine can run the MVP end-to-end.

Install

# Clone + enter repo
cd ~/DevEnv
# (repo already exists locally, update if needed)
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt  # if/when we add one; for now: pip install rich tqdm

Usage

1. Run the ingest server

source venv/bin/activate
python3 scripts/run_ingest.py --port 8841 --token YOUR_SHARED_TOKEN

Options:

• --host (default 127.0.0.1)
• --port (default 8841)
• --inbox (default ~/.auditwalk/inbox.jsonl)
• --token (optional shared secret; bookmarklet must send X-AuditWalk-Token header)

2. Install the bookmarklet

Create a new browser bookmark with the URL field set to:

javascript:(()=>{const data={url:location.href,title:document.title,timestamp:Date.now()/1000,source:'bookmarklet'};fetch('http://127.0.0.1:8841/share',{method:'POST',headers:{'Content-Type':'application/json','X-AuditWalk-Token':'TOKEN_HERE'},body:JSON.stringify(data)}).then(()=>console.log('Sent to AuditWalk')).catch(err=>alert('AuditWalk share failed: '+err));})();

Update TOKEN_HERE if you launched the server with --token.

3. Manage the inbox

python3 scripts/auditwalk_cli.py inbox-list --limit 10
python3 scripts/auditwalk_cli.py inbox-process --clear
python3 scripts/auditwalk_cli.py inbox-add https://example.com --title "Manual"

• inbox-list – prints recent captures.
• inbox-process – dumps entries (optionally --clear).
• inbox-add – helper for manual testing without the bookmarklet.

4. Run the scanner

python3 scanner.py --path /home/adenmediagroup --recent-hours 24 --json-report outputs/scan.json

Flags:

• --no-hash to skip SHA-256 (faster, no dedupe)
• --suspicious-exts ".exe,.dll" to customize detection list
• --json-report to capture structured results for later diffing

Outputs

• Inbox file: ~/.auditwalk/inbox.jsonl (one JSON object per line). Use the CLI to view/process entries.
• Scanner report: Rich tables in the console + optional JSON file containing every record, suspicious hits, and recent-change counts.
• Docs: docs/inbox_workflow.md for the share workflow, plus this README for quick start.

Security Notes

• Ingest server binds to 127.0.0.1 only. Keep it behind a shared token to avoid drive-by localhost POSTs.
• Bookmarklet may require allowing mixed content on strict HTTPS pages.
• Inbox file inherits your home permissions; ensure ~/.auditwalk is not world-readable.
• Scanner skip lists prevent re-hashing this repo and common churn directories; adjust as needed per environment.