Metadata-Version: 2.4
Name: auditwalk
Version: 0.1.1
Summary: AuditWalk
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# 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:

```bash
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:

```bash
make hooks
```

Check whether it is installed:

```bash
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
```bash
# 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
```bash
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
```bash
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
```bash
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.
