Add download and installation instructions to README #4802
2 changed files+209−2
AddedCLAUDE.md+203−0View fileUnifiedSplit
@@ -0,0 +1,203 @@
1# DOWN — AI Security Scanner: Project Blueprint
2
3## Mission
4
5Build the most intelligent, lightweight, ethical antivirus scanner on the market. No scareware. No fake threats. No CPU-destroying background scans. No subscriptions to unlock "protection." Just honest, AI-powered security that respects the user and their machine.
6
7**This is a commercial product.** Every decision must serve the end user, not our revenue.
8
9## Core Principles
10
111. **Lightweight first** — Never spike CPU above 15% during scans. Scan smart, not hard. Use idle-priority threads. Pause if the user is gaming or rendering.
122. **No scareware, ever** — We do NOT inflate threat counts. We do NOT show scary popups to upsell. If something is safe, we say it's safe. Period.
133. **AI-native detection** — Traditional AV relies on hash matching (reactive). We use AI pattern recognition to catch threats that don't exist in any database yet.
144. **Privacy absolute** — Zero telemetry. Zero cloud uploads of user files. All scanning happens locally. The only network call is Claude AI analysis (opt-in, user-initiated).
155. **Transparent** — Open source core. Users can see exactly what we scan and why we flag things.
16
17## Architecture
18
19### Stack
20
21- **Backend**: Rust (performance, safety, small binary ~15MB)
22- **Frontend**: React via Tauri 2.0 (native desktop, no Electron bloat, no HTML served over HTTP)
23- **AI Engine**: Claude API (threat analysis, plain-English explanations)
24- **Target**: Windows primary, Linux/macOS secondary
25
26### Module Map
27
28```
29src-tauri/
30 src/
31 main.rs — Tauri GUI entry, command handlers, Claude API
32 cli_main.rs — CLI entry with clap args
33 lib.rs — Core scan orchestration (full_scan, quick_scan)
34 threat.rs — Threat data model (severity, category, action)
35 scanner/
36 mod.rs — Scanner module registry
37 processes.rs — Running process analysis
38 startup.rs — Registry persistence detection
39 files.rs — File system scanning (hashes, double extensions)
40 browser.rs — Browser extension analysis
41 network.rs — Network config tampering detection
42 scareware.rs — Fake AV / optimizer detection
43 signatures/
44 mod.rs — Signature database loader
45 process_names.rs — Known bad process names (200+)
46 hashes.rs — Known malware SHA256 hashes
47 extension_ids.rs — Malicious browser extension IDs
48 hijacker_domains.rs — DNS hijack domains
49 ip_blocklist.rs — Malicious IP ranges
50 safe_tasks.rs — Legit Windows tasks (false positive prevention)
51 remover.rs — NUKE mode threat removal
52 quarantine.rs — Quarantine with restore capability
53 browser_fix.rs — Browser settings reset
54 elevation.rs — UAC/admin elevation
55 updater.rs — Signature database updates
56 report.rs — Scan report generation
57ui/
58 src/
59 App.jsx — React dashboard (dark theme, threat cards)
60 App.css — Styling (severity color coding)
61```
62
63### Data Flow
64
65```
66User clicks "Scan"
67 → lib.rs orchestrates 6 scanner modules (sequential, low-priority threads)
68 → Each module returns Vec<Threat>
69 → Threats sorted by severity (Critical > High > Medium > Low)
70 → Results displayed in GUI with severity badges
71 → User optionally sends summary to Claude for AI analysis
72 → User can NUKE (auto-remove), quarantine, or manually review
73```
74
75## Current State (v0.3.0)
76
77### Working
78- 6 scanner modules (processes, startup, files, browser, network, scareware)
79- GUI dashboard with dark theme and threat cards
80- CLI mode with full feature parity
81- Claude AI threat analysis (bring your own API key)
82- NUKE mode (aggressive removal)
83- Quarantine with restore capability
84- Browser fix (Chrome, Edge, Firefox)
85- UAC elevation
86- Signature update system
87- CI/CD pipeline (GitHub Actions builds .exe)
88
89### Critical Gaps to Fix
901. **Signature hosting broken** — updater points to non-existent repo `ccantynz-alt/down-scanner`
912. **Hash database empty** — file scanner can't match known malware hashes
923. **Safe tasks list unused** — `safe_tasks.rs` exists but scanner doesn't filter against it, causing false positives
934. **No scan history** — results lost after each scan
945. **No quarantine UI in GUI** — only available via CLI
956. **No progress feedback** — scans appear frozen on large file systems
967. **No signature verification** — downloaded updates not cryptographically verified
978. **Claude model outdated** — hardcoded to Claude 3.5 Sonnet, should use latest Claude Sonnet 4.6
98
99## Roadmap
100
101### Phase 1: Foundation Fixes (Current Priority)
102- [ ] Fix signature hosting (set up real GitHub repo or CDN for signatures.json)
103- [ ] Populate hash database with real malware hashes from public threat feeds
104- [ ] Wire up safe_tasks.rs to prevent false positives on scheduled tasks
105- [ ] Add quarantine list/restore to the GUI dashboard
106- [ ] Add scan progress bar with real-time module status
107- [ ] Update Claude API call to use latest model (claude-sonnet-4-6)
108- [ ] Fix build pipeline — ensure GitHub Release is created with downloadable .exe
109- [ ] Add signature verification (SHA256 checksum for downloaded updates)
110
111### Phase 2: AI-Native Detection
112- [ ] Behavioral analysis — detect suspicious process behavior patterns, not just names
113- [ ] Memory scanning — detect injected code in running processes
114- [ ] Startup chain analysis — map which programs launch which, detect hijacked chains
115- [ ] AI heuristic engine — use Claude to evaluate unknown executables based on metadata
116- [ ] Real-time file monitor — watch Downloads folder for new threats (low-CPU event-driven)
117- [ ] Network traffic analysis — detect C&C communication patterns
118- [ ] Registry change monitor — alert on suspicious registry modifications
119
120### Phase 3: Threat Intelligence
121- [ ] Integrate public threat feeds (VirusTotal, MalwareBazaar, abuse.ch)
122- [ ] Community threat reporting — users can submit new threats (anonymized)
123- [ ] Auto-update signatures on a schedule (daily, background, low-priority)
124- [ ] Threat trend dashboard — show what's currently spreading
125- [ ] Regional threat awareness — threats targeting specific regions
126
127### Phase 4: Commercial Release
128- [ ] Code signing certificate (eliminate SmartScreen warnings)
129- [ ] Auto-updater for the application itself
130- [ ] Licensing system (free tier + pro tier)
131- [ ] Installer (MSI/MSIX for enterprise deployment)
132- [ ] Documentation site
133- [ ] User onboarding flow
134- [ ] Crash reporting (opt-in, no PII)
135
136## Build Commands
137
138### Linux / macOS
139```bash
140cd ui && npm install && npm run build && cd ..
141cargo build --release
142```
143
144### Windows (PowerShell)
145```powershell
146cd ui; npm install; npm run build; cd ..
147cargo build --release
148```
149
150### Output
151- Binary: `target/release/down.exe` (Windows) or `target/release/down` (Linux/macOS)
152- CI builds: GitHub Actions creates release with .exe and installer zip on version tags
153
154## Development Rules
155
156### Before Every Build
1571. Read this CLAUDE.md file first
1582. Check the roadmap — what phase are we in?
1593. Check existing scanner modules before adding new ones
1604. Run `cargo check` before `cargo build` to catch errors fast
161
162### Code Standards
163- **No HTML files** — all UI goes through React/Tauri components
164- **No unnecessary dependencies** — every crate must justify its inclusion
165- **CPU discipline** — any scan loop must yield periodically, never block the UI thread
166- **False positive prevention** — every detection rule needs a safe-list counterpart
167- **Error handling** — use Result<>, never panic in production code
168- **No telemetry** — never add network calls that the user didn't explicitly request
169
170### Threat Detection Rules
171- Every threat must have: name, description, severity, category, and recommended action
172- Severity must be honest — don't inflate to scare users
173- Always provide a "Manual Review" option for uncertain detections
174- Quarantine before delete — give users a way to recover false positives
175- NUKE mode is opt-in only, never automatic
176
177### Scanner Module Template
178When adding a new scanner module:
1791. Create `src-tauri/src/scanner/{module_name}.rs`
1802. Implement `pub fn scan_{module_name}() -> Vec<Threat>`
1813. Register in `scanner/mod.rs`
1824. Add to `lib.rs` scan orchestration
1835. Add corresponding signature file if needed in `signatures/`
1846. Update this CLAUDE.md roadmap
185
186## Competitive Positioning
187
188### What We Do Better
189- **Honest** — we don't manufacture threats to sell upgrades
190- **Lightweight** — <15% CPU, <100MB RAM during scans
191- **AI-powered** — Claude provides human-readable threat explanations
192- **Transparent** — open source, users can audit every detection rule
193- **Respectful** — no popups, no nagging, no "your PC is at risk" nonsense
194
195### What Traditional AV Gets Wrong
196- Constant background scanning that destroys system performance
197- Inflated threat counts to justify subscription renewals
198- Bundled browser toolbars and "safe search" hijackers
199- Blocking legitimate software as "potentially unwanted"
200- Selling user browsing data to advertisers
201- Disabling Windows Defender to force dependency on their product
202
203We exist because the antivirus industry became the very thing it was supposed to protect against.
ModifiedREADME.md+6−2View fileUnifiedSplit
@@ -51,11 +51,15 @@ Go to the [Releases](https://github.com/ccantynz-alt/windows-security-scanner/re
5151
5252Requires [Rust](https://rustup.rs/) and [Node.js](https://nodejs.org/).
5353
54### Linux / macOS (bash)
5455```bash
55# Build the frontend
5656cd ui && npm install && npm run build && cd ..
57cargo build --release
58```
5759
58# Build the app
60### Windows (PowerShell)
61```powershell
62cd ui; npm install; npm run build; cd ..
5963cargo build --release
6064```
6165
6266
c comment · e edit title · m merge · a approve · r request changes · ? shortcuts