End-to-end research workflow: analytics, graceful shutdown, CLI fixes, UX improvements, README

README.md

@@ -1,16 +1,18 @@
-# macaronV2
+# macaron
 
-Fast reconnaissance workflow in Go with SQLite-backed persistence and an operator-focused dashboard.
+Reconnaissance workflow tool written in Go. SQLite-backed persistence, a live CLI progress view, and a web dashboard for inspecting findings.
 
-## The Model
+## Workflow
 
-`macaronV2` is designed around one simple loop:
+```
+setup → scan → status/results → serve → export
+```
 
-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
+1. **setup** – verify tool installation and configure API keys
+2. **scan** – collect subdomains, probe live hosts, scan ports, discover URLs, run vuln checks
+3. **status / results** – triage findings in the terminal
+4. **serve** – open everything in the web dashboard
+5. **export** – write a JSON report for sharing or archiving
 
 ## Quick Start
 
@@ -24,73 +26,109 @@ source ~/.bashrc
 macaron setup
 macaron scan example.com --profile balanced
 macaron status
-macaron serve --addr 127.0.0.1:8088
+macaron serve
 ```
 
-## Core Commands
+## Commands
 
-```bash
-macaron setup
-macaron scan <target...>
-macaron status
-macaron results -d <domain> -w <type>
-macaron serve
-macaron export -o results.json
+```
+macaron setup                              Show tool installation status
+macaron scan <target>                      Scan a target
+macaron status                             List recent scans
+macaron results --dom <domain>             Show results for a domain
+macaron serve                              Start the web dashboard
+macaron export --out results.json          Export all results to JSON
+macaron guide                              Show workflow guide
+```
+
+## Scan Options
+
+```
+--profile passive|balanced|aggressive      Workflow preset (default: balanced)
+--stages subdomains,http,ports,urls,vulns  Enable specific stages (default: all)
+--mod wide|narrow|fast|deep|osint          Scan mode (default: wide)
+--rate N                                   Request rate hint (default: 150)
+--threads N                                Worker threads (default: 30)
+--fil FILE                                 Read targets from a file
+--inp                                      Read targets from stdin
 ```
 
 ## Profiles
 
-- `passive`: low-noise collection
-- `balanced`: default practical workflow
-- `aggressive`: high-throughput authorized testing
+| Profile    | Rate | Threads | Stages                  |
+|------------|------|---------|-------------------------|
+| passive    | 40   | 10      | subdomains, http, urls  |
+| balanced   | 150  | 30      | all                     |
+| aggressive | 350  | 70      | all                     |
 
 ## Storage
 
 Default storage root: `./storage`
 
-```text
+```
 storage/
-  macaron.db
-  config.yaml
+  macaron.db          SQLite database with all scan results
+  config.yaml         API key configuration
   <target>/
-    <scan-id>.json
-    latest.txt
+    <scan-id>.json    Full scan result
+    latest.txt        ID of the most recent scan for this target
 ```
 
-## Setup & API Keys
+## API Keys
 
 ```bash
-macaron setup
-macaron --install-tools
 macaron --set-api securitytrails=YOUR_KEY
 macaron --show-api
 ```
 
-## Stage Control
+## Stages
+
+| Stage      | What it does                                |
+|------------|---------------------------------------------|
+| subdomains | crt.sh + subfinder/assetfinder/findomain    |
+| http       | probe each host over HTTPS then HTTP        |
+| ports      | TCP connect scan on common ports            |
+| urls       | Wayback Machine URL discovery               |
+| vulns      | nuclei template scan against live hosts     |
+
+## Web Dashboard
 
 ```bash
-macaron scan example.com --stages subdomains,http,urls
+macaron serve --addr 127.0.0.1:8088
 ```
 
-Available stages: `subdomains,http,ports,urls,vulns`
+Open `http://127.0.0.1:8088`.
 
-## Dashboard
+The dashboard shows scan results, a live host table, subdomain lists, URLs, vulnerability findings, a geo heat map, and an **analytics** view with daily activity, top targets by vuln count, and severity distribution across all scans. Press `Ctrl-C` to stop.
+
+## Install
 
 ```bash
-macaron serve --addr 127.0.0.1:8088
+git clone https://github.com/root-Manas/macaron.git
+cd macaron
+./install.sh        # builds and installs to ~/.local/bin/macaron
+source ~/.bashrc
+macaron --version
 ```
 
-Open `http://127.0.0.1:8088`.
+The installer requires Go 1.22 or later. To install optional external tools:
+
+```bash
+macaron setup          # show what is installed and what is missing
+macaron --ins          # install missing Go-based tools (Linux)
+```
 
 ## Release
 
+Tag a version to trigger the CI build and binary release:
+
 ```bash
-git tag v3.0.1
-git push origin v3.0.1
+git tag v3.x.x
+git push origin v3.x.x
 ```
 
-Tagged releases build and publish binaries for Linux, macOS, and Windows.
+Binaries are published for Linux, macOS, and Windows.
 
-## Security Note
+## Security
 
 Use only on systems you own or are explicitly authorized to test.

cmd/macaron/main.go

@@ -100,7 +100,7 @@ func run() int {
 	pflag.Parse()
 
 	if showVersion {
-		fmt.Printf("macaronV2 %s (Go %s, stable)\n", version, runtime.Version())
+		fmt.Printf("macaron %s (Go %s)\n", version, runtime.Version())
 		return 0
 	}
 	if guide {
@@ -170,7 +170,7 @@ func run() int {
 		return 0
 	}
 	if pipeline {
-		fmt.Printf("Pipeline (macaronV2 native): %s\n", filepath.Join(home, "pipeline.v2.yaml"))
+		fmt.Printf("Pipeline config path: %s\n", filepath.Join(home, "pipeline.v2.yaml"))
 		return 0
 	}
 	if listTools {
@@ -211,8 +211,10 @@ func run() int {
 		return 0
 	}
 	if serve {
+		ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
+		defer stop()
 		server := ui.New(application.Store)
-		if err := server.Serve(serveAddr); err != nil {
+		if err := server.Serve(ctx, serveAddr); err != nil {
 			fmt.Fprintf(os.Stderr, "error: %v\n", err)
 			return 1
 		}
@@ -276,42 +278,69 @@ func run() int {
 		return 1
 	}
 	if !quiet {
-		fmt.Println("macaronV2 scan summary")
+		fmt.Println("scan summary")
 		fmt.Println(app.RenderScanSummary(res))
 		fmt.Printf("Completed %d target(s) in %s\n", len(res), time.Since(start).Round(time.Millisecond))
+		if len(res) > 0 {
+			tgt := res[0].Target
+			fmt.Printf("\nWhat next?\n")
+			fmt.Printf("  macaron status\n")
+			fmt.Printf("  macaron results --dom %s --wht live\n", tgt)
+			fmt.Printf("  macaron results --dom %s --wht vulns\n", tgt)
+			fmt.Printf("  macaron serve\n")
+		}
 	}
 	return 0
 }
 
 func printHelp() {
-	fmt.Println(`macaronV2 (Go stable rewrite)
+	fmt.Println(`macaron - reconnaissance workflow tool
 
 Usage:
   macaron scan example.com
+  macaron scan example.com --profile passive
+  macaron scan example.com --stages subdomains,http,urls
   macaron status
-  macaron results -dom example.com -wht live
-  macaron serve -adr 127.0.0.1:8088
+  macaron results --dom example.com --wht live
+  macaron serve --addr 127.0.0.1:8088
   macaron setup
+  macaron export --out results.json
+
+Core commands:
+  scan TARGET            Scan one or more targets (positional or --scn)
+  status                 Show recent scan summaries
+  results                Show detailed scan results
+  serve                  Start web dashboard
+  setup                  Show tool installation status
+  export                 Export scan results to JSON
+  guide                  Show workflow guide
+
+Scan flags:
+  --scn TARGET           Scan one or more targets (repeatable)
+  --fil FILE             Read targets from file
+  --inp                  Read targets from stdin
+  --profile NAME         passive|balanced|aggressive (default: balanced)
+  --stages LIST          subdomains,http,ports,urls,vulns (default: all)
+  --mod MODE             wide|narrow|fast|deep|osint
+  --rate N               Request rate hint (default: 150)
+  --threads N            Worker threads (default: 30)
 
-Core flags:
-  -scn TARGET            Scan one or more targets
-  -fil FILE              Read targets from file
-  -inp                   Read targets from stdin
-  -mod MODE              wide|narrow|fast|deep|osint
-  -sts                   Show scan summaries
-  -res                   Show scan details
-  -exp                   Export JSON
-  -lst                   Show tool availability
-  -str DIR               Use custom storage root (default ./storage)
-  -stg LIST              Choose stages: subdomains,http,ports,urls,vulns
-  -sak k=v               Save API keys to storage config.yaml
-  -shk                   Show masked API keys
-  -stp                   Show setup screen with tool status
-  -ins                   Install missing supported tools (Linux)
-  -prf NAME              passive|balanced|aggressive
-  -gud                   Show first-principles workflow guide
-  -srv                   Start browser dashboard
-  -ver                   Show version`)
+Output flags:
+  --dom DOMAIN           Filter results by domain
+  --wht VIEW             all|subdomains|live|ports|urls|js|vulns
+  --lim N                Output row limit (default: 50)
+  --out FILE             Output file path
+  --quiet                Suppress progress output
+
+API keys:
+  --set-api k=v          Save API key (e.g. securitytrails=KEY)
+  --show-api             Show configured API keys (masked)
+
+Other:
+  --storage DIR          Storage root (default: ./storage)
+  --addr ADDR            Dashboard bind address (default: 127.0.0.1:8088)
+  --version              Show version
+  --guide                Show first-principles workflow guide`)
 }
 
 func normalizeLegacyArgs() {
@@ -341,9 +370,6 @@ func normalizeCommandArgs() {
 			}
 			args = append(args, "--scn", tok)
 		}
-		if len(args) == 1 {
-			args = append(args, "--scn")
-		}
 		os.Args = args
 	case "status":
 		os.Args = append([]string{os.Args[0], "--sts"}, rest...)
@@ -456,30 +482,30 @@ func applyProfile(profile string, mode *string, rate *int, threads *int, stages
 }
 
 func printGuide() {
-	fmt.Println(`macaronV2 guide (first-principles workflow)
+	fmt.Println(`macaron workflow guide
 
 1) Setup once:
    macaron setup
-   macaron -ins
-   macaron -sak securitytrails=YOUR_KEY
+   macaron --ins
+   macaron --set-api securitytrails=YOUR_KEY
 
-2) Run intentional scans:
-   macaron scan target.com -prf passive
-   macaron scan target.com -prf balanced
-   macaron scan target.com -prf aggressive -stg subdomains,http,ports,urls,vulns
+2) Run scans:
+   macaron scan target.com --profile passive
+   macaron scan target.com --profile balanced
+   macaron scan target.com --profile aggressive --stages subdomains,http,ports,urls,vulns
 
-3) Inspect and decide:
+3) Inspect and triage:
    macaron status
-   macaron results -dom target.com -wht live
+   macaron results --dom target.com --wht live
    macaron serve
 
-4) Export/share:
-   macaron export -out target.json
+4) Export:
+   macaron export --out target.json
 
 Profiles:
-  passive    low-noise, low-rate, mostly passive collection
-  balanced   default practical pipeline
-  aggressive high concurrency for authorized deep testing only`)
+  passive      low rate, low concurrency, passive collection only
+  balanced     default practical pipeline
+  aggressive   high concurrency for authorized deep testing only`)
 }
 
 func macaronHome(override string) (string, error) {

install.sh

@@ -10,14 +10,25 @@ if ! command -v go >/dev/null 2>&1; then
 fi
 
 mkdir -p "$HOME/.local/bin"
-echo "[macaronV2] building binary..."
+echo "[macaron] building binary..."
 go mod tidy
 go build -o "$HOME/.local/bin/macaron" ./cmd/macaron
 chmod +x "$HOME/.local/bin/macaron"
 
-if ! grep -q 'export PATH="$HOME/.local/bin:$PATH"' "$HOME/.bashrc" 2>/dev/null; then
-  echo 'export PATH="$HOME/.local/bin:$PATH"' >> "$HOME/.bashrc"
-fi
+PATH_LINE='export PATH="$HOME/.local/bin:$PATH"'
+
+add_to_profile() {
+  local profile="$1"
+  if [ -f "$profile" ] && ! grep -qF 'HOME/.local/bin' "$profile" 2>/dev/null; then
+    echo "$PATH_LINE" >> "$profile"
+    echo "[macaron] added PATH entry to $profile"
+  fi
+}
+
+add_to_profile "$HOME/.bashrc"
+add_to_profile "$HOME/.zshrc"
+add_to_profile "$HOME/.profile"
 
-echo "[macaronV2] installed to $HOME/.local/bin/macaron"
-echo "[macaronV2] run: macaron --version"
+echo "[macaron] installed to $HOME/.local/bin/macaron"
+echo "[macaron] restart your shell or run:  export PATH=\"\$HOME/.local/bin:\$PATH\""
+echo "[macaron] then run:  macaron --version"