Merge PR #25 and PR #27 into fix-conflicts-and-merge, resolving all conflicts

README.md

@@ -1,157 +1,207 @@
-# macaronV2
+# macaron
 
-Fast reconnaissance workflow in Go with SQLite-backed persistence and an operator-focused dashboard.
+Fast, researcher-oriented recon framework. Runs a chained enumeration pipeline — subdomains → live probing → port mapping → URL harvesting → vuln scanning — and stores everything in a local SQLite-backed store you can query and export.
 
-```
-  ╔╦╗╔═╗╔═╗╔═╗╦═╗╔═╗╔╗╔
-  ║║║╠═╣║  ╠═╣╠╦╝║ ║║║║
-  ╩ ╩╩ ╩╚═╝╩ ╩╩╚═╚═╝╝╚╝
-
-  Fast Recon Workflow  v3.0.0
-  github.com/root-Manas/macaron
-  ────────────────────────────────────────
-```
-
-## The Model
-
-`macaronV2` is designed around one simple loop:
-
-1. `setup` toolchain and keys
-2. `scan` targets with an explicit profile
-3. `status/results` to triage findings
-4. `serve` to inspect everything in one dashboard
-5. `export` to share/report
+---
 
-## Quick Start
+## install
 
 ```bash
 git clone https://github.com/root-Manas/macaron.git
 cd macaron
 chmod +x install.sh
 ./install.sh
 source ~/.bashrc
+```
+
+Or grab a tagged binary from [Releases](https://github.com/root-Manas/macaron/releases).
+
+---
 
-macaron setup
-macaron scan example.com -prf balanced
+## quick start
+
+```bash
+macaron setup --install          # check and install missing tools
+macaron api set securitytrails=KEY shodan=KEY
+macaron scan -t example.com
 macaron status
-macaron serve
+macaron results -d example.com -w live
+macaron export -o example.json
 ```
 
-## Core Commands
+---
+
+## commands
 
 ```
-USAGE
-  macaron scan example.com
-  macaron status
-  macaron results -dom example.com -wht live
-  macaron serve -adr 127.0.0.1:8088
-  macaron setup
-  macaron export -out results.json
-
-SCAN FLAGS
-  -scn TARGET   Scan one or more targets (repeatable)
-  -fil FILE     Read targets from file
-  -inp          Read targets from stdin
-  -mod MODE     Scan mode: wide|narrow|fast|deep|osint
-  -stg LIST     Stages: subdomains,http,ports,urls,vulns
-  -prf NAME     Profile: passive|balanced|aggressive
-  -rte N        Request rate hint (default: 150)
-  -thr N        Worker threads (default: 30)
-
-OUTPUT FLAGS
-  -sts          Show recent scan summaries
-  -res          Show scan results
-  -dom DOMAIN   Filter by domain
-  -wht TYPE     Result view: all|subdomains|live|ports|urls|js|vulns
-  -lim N        Output limit (default: 50)
-  -exp          Export results to JSON
-  -qut          Quiet mode (suppress banner and progress)
-
-API KEYS
-  -sak k=v      Set API key (e.g. -sak securitytrails=KEY)
-  -shk          Show masked API keys
-
-DASHBOARD
-  -srv          Start browser dashboard
-  -adr ADDR     Bind address (default: 127.0.0.1:8088)
-
-TOOLS & CONFIG
-  -stp          Show tool installation status
-  -ins          Install missing supported tools (Linux)
-  -lst          List external tool availability
-  -str DIR      Custom storage root (default: ./storage)
-  -nc           Disable color output
-  -ver          Show version
+macaron scan       run recon pipeline
+macaron status     list past scans
+macaron results    query scan output
+macaron setup      tool inventory + auto-install
+macaron export     dump results to JSON
+macaron config     show storage paths
+macaron api        manage global API keys
+macaron uninstall  remove macaron from this machine
+macaron guide      workflow walkthrough
+macaron version    print version
 ```
 
-## Profiles
+---
 
-| Profile     | Description                                        |
-|-------------|----------------------------------------------------|
-| `passive`   | Low-noise, low-rate, mostly passive collection     |
-| `balanced`  | Default practical workflow (recommended)           |
-| `aggressive`| High-throughput for authorized deep testing only   |
+## scan
 
-## CLI UX
+```bash
+macaron scan -t target.com
+macaron scan -t target.com -p passive
+macaron scan -t target.com -p aggressive --stages subdomains,http,ports,urls,vulns
+macaron scan -f targets.txt -p balanced -q
+cat domains.txt | macaron scan --stdin
+```
 
-macaron follows the same UX patterns as ProjectDiscovery tools (nuclei, httpx, subfinder):
+**flags**
 
-- **Colored log levels**: `[INF]`, `[WRN]`, `[ERR]`, `[OK]` with distinct colors
-- **Live progress**: Braille-spinner with stage and elapsed time during scans
-- **Colored tables**: Vulns highlighted in red, live hosts in green
-- **Compact flags**: Short (`-scn`, `-mod`, `-prf`) with full-word aliases also accepted
-- **NO_COLOR support**: Respects the `NO_COLOR` environment variable
-- **Quiet mode**: `-qut` suppresses banner and progress for scripted use
+| flag | default | description |
+|------|---------|-------------|
+| `-t, --target` | — | target domain (repeatable) |
+| `-f, --file` | — | read targets from file |
+| `--stdin` | — | read targets from stdin |
+| `-m, --mode` | `wide` | `wide` \| `narrow` \| `fast` \| `deep` \| `osint` |
+| `-p, --profile` | `balanced` | `passive` \| `balanced` \| `aggressive` |
+| `--stages` | `all` | comma-separated: `subdomains,http,ports,urls,vulns` |
+| `--rate` | `150` | request rate hint |
+| `--threads` | `30` | concurrent workers |
+| `-q, --quiet` | — | suppress progress output |
+| `--storage` | `./storage` | custom storage root |
 
-## Storage
+**profiles**
 
-Default storage root: `./storage`
+| profile | behaviour |
+|---------|-----------|
+| `passive` | OSINT-only, low rate, no active scanning |
+| `balanced` | enumeration + probing + vuln scan |
+| `aggressive` | max concurrency, all stages — authorized testing only |
 
-```text
-storage/
-  macaron.db
-  config.yaml
-  <target>/
-    <scan-id>.json
-    latest.txt
-```
+---
+
+## pipeline stages
+
+| stage | what it does | tools used |
+|-------|-------------|------------|
+| `subdomains` | passive + active enumeration | crt.sh, subfinder, assetfinder, findomain, amass + SecurityTrails API |
+| `http` | probe live hosts, grab titles | httpx fallback (native prober) |
+| `ports` | TCP port sweep | naabu (if installed), native TCP dial fallback |
+| `urls` | passive + active URL harvest | Wayback CDX, gau, katana |
+| `vulns` | template-based vuln detection | nuclei |
+
+Tools are used automatically when installed. Missing tools are skipped — pipeline keeps running.
+
+---
+
+## api management
 
-## Setup & API Keys
+macaron maintains a single global key store. All tools it runs pick up keys from here automatically — you don't configure them per-tool.
 
 ```bash
-macaron setup
-macaron -ins
-macaron -sak securitytrails=YOUR_KEY
-macaron -shk
+# set keys
+macaron api set securitytrails=KEY shodan=KEY virustotal=KEY github=TOKEN
+
+# remove a key
+macaron api unset shodan
+
+# view (masked)
+macaron api list
+
+# import from tools already on your system (subfinder, amass…)
+macaron api import
+
+# load many keys at once from a YAML file
+macaron api bulk -f keys.yaml
 ```
 
-## Stage Control
+**bulk file format**
 
-```bash
-macaron scan example.com -stg subdomains,http,urls
+```yaml
+api_keys:
+  securitytrails: YOUR_KEY
+  shodan: YOUR_KEY
+  virustotal: YOUR_KEY
+  chaos: YOUR_KEY
+  binaryedge: YOUR_KEY
+  github: YOUR_TOKEN
 ```
 
-Available stages: `subdomains`, `http`, `ports`, `urls`, `vulns`
+Keys are written to `<storage>/config.yaml`. When subfinder runs, macaron injects the configured keys via a temporary provider config — your existing subfinder config is never modified.
+
+---
 
-## Dashboard
+## results
 
 ```bash
-macaron serve
-# or with custom address:
-macaron serve -adr 127.0.0.1:8088
+macaron status                          # recent scans
+macaron results -d example.com          # full JSON
+macaron results -d example.com -w live  # live hosts only
+macaron results -d example.com -w vulns # findings only
+macaron results --id <scan-id>          # specific scan
 ```
 
-Open `http://127.0.0.1:8088` — includes scan list with mode filters, health badges, URL yield trend, and geo map.
+**-w values**: `all` · `subdomains` · `live` · `ports` · `urls` · `js` · `vulns`
 
-## Release
+---
+
+## storage layout
+
+```
+storage/
+  macaron.db          # indexed scan store
+  config.yaml         # API keys + settings
+  <target>/
+    <scan-id>.json
+    latest.txt
+```
+
+Override with `--storage /path/to/dir` or `MACARON_HOME` (env not yet supported — use the flag).
+
+---
+
+## setup
 
 ```bash
-git tag v3.0.1
-git push origin v3.0.1
+macaron setup           # show tool inventory
+macaron setup --install # auto-install missing tools that support it
 ```
 
-Tagged releases build and publish binaries for Linux, macOS, and Windows.
+Supported tools (auto-installed with `--install`):
+
+| tool | role |
+|------|------|
+| subfinder | subdomain enumeration |
+| assetfinder | subdomain enumeration |
+| amass | subdomain enumeration |
+| httpx | HTTP probing |
+| dnsx | DNS resolution |
+| naabu | port scanning |
+| gau | passive URL discovery |
+| waybackurls | passive URL discovery |
+| katana | active web crawling |
+| gospider | active web crawling |
+| hakrawler | active web crawling |
+| ffuf | content fuzzing |
+| gobuster | content fuzzing |
+| nuclei | vulnerability scanning |
+
+---
+
+## uninstall
+
+```bash
+macaron uninstall
+```
+
+Locates and removes the macaron binary from PATH. Optionally removes the storage directory when prompted. Pass `--yes` to skip confirmation.
+
+---
+
+## security
 
-## Security Note
+Use macaron only on systems you own or have explicit written authorization to test.
 
-Use only on systems you own or are explicitly authorized to test.