osintkit 0.1.4 → 0.1.5

package/README.md

@@ -33,7 +33,9 @@ osintkit open       # View profile details + open latest report
 | `osintkit refresh [id]` | Re-run scan for a profile |
 | `osintkit open [id]` | Show profile details and open latest report |
 | `osintkit export [id]` | Export as JSON or Markdown |
-| `osintkit setup` | Configure API keys |
+| `osintkit setup` | Configure API keys interactively (preserves existing keys) |
+| `osintkit config set-key <key> <value>` | Update a single API key without touching others |
+| `osintkit config show` | Show which API keys are set (values hidden) |
 | `osintkit delete [id]` | Delete a profile |
 | `osintkit version` | Show version |
 
@@ -56,19 +58,19 @@ osintkit open       # View profile details + open latest report
 | Data brokers | name/email | Google CSE broker scan |
 | Dark web | email | Ahmia / public index |
 | Breach lookup | email | BreachDirectory |
+| GitHub | username | Public profile (always runs, no key needed) |
 
-### Stage 2 — Optional free API keys, runs first when configured
+### Stage 2 — Optional API keys, unlocks extra data sources
 
-| Service | Input | Free Tier |
-|---------|-------|-----------|
-| HaveIBeenPwned | email | Free w/ key |
+| Service | Input | Tier |
+|---------|-------|------|
+| HaveIBeenPwned | email | Paid ($3.50/month) |
 | LeakCheck | email/phone/user | Free tier |
-| NumVerify | phone | 100/month |
-| Hunter.io | name + domain | 50/month |
-| GitHub API | username | 5000/hr w/ key |
-| SecurityTrails | domain | Free tier |
+| NumVerify | phone | 100/month free |
+| Hunter.io | email | 25/month free |
+| SecurityTrails | domain | Paid |
 
-Stage 2 always runs first when a key is configured. If rate-limited or key missing, falls back to Stage 1 automatically.
+Stage 2 modules only run when a key is configured. If rate-limited, the scan continues gracefully with Stage 1 results — rate-limited modules are shown as yellow, not red.
 
 ## Output
 
@@ -81,23 +83,25 @@ Risk score is 0–100 based on breach exposure, social footprint, data broker li
 
 ## API Keys (All Optional)
 
-Run `osintkit setup` to configure. All keys are optional — the tool works without any of them.
+Keys are stored in `~/.osintkit/config.yaml` (permissions: 600).
 
-```
-~/.osintkit/config.yaml
+```bash
+osintkit config set-key hunter YOUR_KEY    # add or update one key
+osintkit config show                        # see which keys are set
+osintkit setup                              # interactive wizard (preserves existing keys)
 ```
 
-| Service | Get key at |
-|---------|-----------|
-| HaveIBeenPwned | haveibeenpwned.com/API/Key |
-| LeakCheck | leakcheck.io |
-| NumVerify | numverify.com |
-| Hunter.io | hunter.io |
-| GitHub | github.com/settings/tokens |
-| Intelbase | intelbase.is |
-| BreachDirectory | rapidapi.com |
-| Google CSE | developers.google.com/custom-search |
-| SecurityTrails | securitytrails.com |
+| Service | Where to get it | Free? |
+|---------|----------------|-------|
+| HaveIBeenPwned | haveibeenpwned.com/API/Key | Paid ($3.50/mo) |
+| LeakCheck | leakcheck.io | Free tier |
+| NumVerify | numverify.com | 100 req/month free |
+| Hunter.io | hunter.io | 25 req/month free |
+| GitHub | github.com/settings/tokens | Free (raises rate limit) |
+| Intelbase | intelbase.is | 100 req/month free |
+| BreachDirectory | rapidapi.com (search "BreachDirectory") | 50 req/day free |
+| Google CSE | developers.google.com/custom-search | 100 req/day free |
+| SecurityTrails | securitytrails.com | Paid |
 
 ## Run from Source
 

package/osintkit/__init__.py

@@ -1,3 +1,3 @@
 """osintkit - OSINT CLI tool for personal digital footprint analysis."""
 
-__version__ = "0.1.4"
+__version__ = "0.1.5"

package/osintkit/cli.py

@@ -17,8 +17,9 @@ from rich.progress import Progress, SpinnerColumn, TextColumn
 
 from osintkit import __version__
 from osintkit.scanner import Scanner
-from osintkit.config import load_config, Config, APIKeys
+from osintkit.config import load_config, save_config, Config, APIKeys
 from osintkit.profiles import Profile, ProfileStore, ScanHistory
+from osintkit.setup import update_api_key
 
 app = typer.Typer(help="OSINT CLI for personal digital footprint analysis", invoke_without_command=True)
 console = Console()
@@ -291,20 +292,15 @@ def run_scan_for_profile(profile: Profile) -> dict:
 
 @app.command()
 def setup():
-    """Configure API keys."""
+    """Configure API keys. Existing keys are preserved unless a new value is entered."""
     config_path = Path.home() / ".osintkit" / "config.yaml"
-    
-    if config_path.exists():
-        console.print(f"\n[yellow]Config already exists: {config_path}[/yellow]")
-        if not Confirm.ask("Overwrite?"):
-            return
-    
+    existing = load_config(config_path)
+
     console.print("\n[bold cyan]═══ API Key Setup ═══[/bold cyan]\n")
-    console.print("Enter your API keys (press Enter to skip).\n")
-    
-    keys = {}
+    console.print("Press [bold]Enter[/bold] to keep an existing key. Type a new value to update it.\n")
+
     api_key_list = [
-        ("hibp", "HaveIBeenPwned (hibp)", "https://haveibeenpwned.com/API/Key"),
+        ("hibp", "HaveIBeenPwned", "https://haveibeenpwned.com/API/Key"),
         ("breachdirectory", "BreachDirectory", "https://rapidapi.com/"),
         ("leakcheck", "LeakCheck", "https://leakcheck.io/"),
         ("intelbase", "Intelbase", "https://intelbase.is/"),
@@ -316,37 +312,62 @@ def setup():
         ("github", "GitHub Personal Access Token", "https://github.com/settings/tokens"),
         ("securitytrails", "SecurityTrails", "https://securitytrails.com"),
     ]
-    
+
+    keys_dict = existing.api_keys.model_dump()
+
     for key_name, label, url in api_key_list:
+        current = keys_dict.get(key_name, "")
+        status = "[green][set][/green]" if current else "[dim][not set][/dim]"
         hint = f" ({url})" if url else ""
-        value = Prompt.ask(f"{label}{hint}", default="")
-        keys[key_name] = value.strip()
-    
-    config_path.parent.mkdir(parents=True, exist_ok=True)
-    config_content = f"""# osintkit Configuration
-output_dir: ~/osint-results
-timeout_seconds: 120
-
-api_keys:
-  hibp: "{keys.get('hibp', '')}"
-  breachdirectory: "{keys.get('breachdirectory', '')}"
-  leakcheck: "{keys.get('leakcheck', '')}"
-  intelbase: "{keys.get('intelbase', '')}"
-  google_cse_key: "{keys.get('google_cse_key', '')}"
-  google_cse_cx: "{keys.get('google_cse_cx', '')}"
-  numverify: "{keys.get('numverify', '')}"
-  emailrep: "{keys.get('emailrep', '')}"
-  resend: ""
-  hunter: "{keys.get('hunter', '')}"
-  github: "{keys.get('github', '')}"
-  securitytrails: "{keys.get('securitytrails', '')}"
-  epieos: ""
-"""
-    config_path.write_text(config_content)
-    config_path.chmod(0o600)  # API keys must not be world-readable
+        value = Prompt.ask(f"  {status} {label}{hint}", default="")
+        if value.strip():
+            keys_dict[key_name] = value.strip()
+
+    updated = Config(
+        output_dir=existing.output_dir,
+        timeout_seconds=existing.timeout_seconds,
+        api_keys=APIKeys(**keys_dict),
+    )
+    save_config(updated, config_path)
     console.print(f"\n[green]✓[/green] Config saved: {config_path}")
 
 
+config_app = typer.Typer(help="Manage osintkit configuration.")
+app.add_typer(config_app, name="config")
+
+
+@config_app.command("set-key")
+def config_set_key(
+    key: str = typer.Argument(..., help="API key name (e.g. github, hunter)"),
+    value: str = typer.Argument(..., help="The API key value"),
+):
+    """Update a single API key without touching others."""
+    valid_keys = set(APIKeys.model_fields.keys())
+    if key not in valid_keys:
+        console.print(f"[red]Unknown key '{key}'.[/red]")
+        console.print(f"Valid keys: {', '.join(sorted(valid_keys))}")
+        raise typer.Exit(1)
+    update_api_key(key, value)
+
+
+@config_app.command("show")
+def config_show():
+    """Show which API keys are set (values are not shown)."""
+    config_path = Path.home() / ".osintkit" / "config.yaml"
+    cfg = load_config(config_path)
+    keys_dict = cfg.api_keys.model_dump()
+
+    table = Table(title="API Keys", show_header=True)
+    table.add_column("Key", style="cyan")
+    table.add_column("Status")
+
+    for key_name in sorted(keys_dict.keys()):
+        status = "[green]set[/green]" if keys_dict[key_name] else "[dim]not set[/dim]"
+        table.add_row(key_name, status)
+
+    console.print(table)
+
+
 @app.command()
 def new():
     """Create a new person profile."""

package/osintkit/config.py

@@ -32,6 +32,19 @@ class Config(BaseModel):
     api_keys: APIKeys = Field(default_factory=APIKeys)
 
 
+def save_config(config: Config, config_path: Path) -> None:
+    """Save configuration to YAML file."""
+    config_path.parent.mkdir(parents=True, exist_ok=True)
+    data = {
+        "output_dir": config.output_dir,
+        "timeout_seconds": config.timeout_seconds,
+        "api_keys": config.api_keys.model_dump(),
+    }
+    with open(config_path, "w") as f:
+        yaml.dump(data, f, default_flow_style=False)
+    config_path.chmod(0o600)
+
+
 def load_config(config_path: Path) -> Config:
     """Load configuration from YAML file.
 

package/osintkit/modules/__init__.py

@@ -3,4 +3,14 @@
 
 class ModuleError(Exception):
     """Base exception for module failures."""
+    pass
+
+
+class RateLimitError(ModuleError):
+    """Raised when an API rate limit (429) is hit."""
+    pass
+
+
+class InvalidKeyError(ModuleError):
+    """Raised when an API key is invalid or unauthorized (401/403)."""
     pass

package/osintkit/modules/stage2/github_api.py

@@ -4,6 +4,8 @@ from typing import Dict, List
 
 import httpx
 
+from osintkit.modules import RateLimitError, InvalidKeyError
+
 
 async def run(inputs: dict, api_key: str) -> List[Dict]:
     """Look up a GitHub user profile via the GitHub REST API.
@@ -23,19 +25,20 @@ async def run(inputs: dict, api_key: str) -> List[Dict]:
         return []
 
     try:
+        headers = {"Accept": "application/vnd.github.v3+json"}
+        if api_key:
+            headers["Authorization"] = f"token {api_key}"
+
         async with httpx.AsyncClient(timeout=httpx.Timeout(10.0, connect=5.0)) as client:
             response = await client.get(
                 f"https://api.github.com/users/{username}",
-                headers={
-                    "Authorization": f"token {api_key}",
-                    "Accept": "application/vnd.github.v3+json",
-                },
+                headers=headers,
             )
 
         if response.status_code == 429:
-            raise Exception("429 rate limited")
+            raise RateLimitError("GitHub API rate limit reached")
         if response.status_code in (401, 403):
-            raise Exception("401 invalid key")
+            raise InvalidKeyError("GitHub token invalid or unauthorized")
         if response.status_code == 404:
             return []
 
@@ -59,7 +62,7 @@ async def run(inputs: dict, api_key: str) -> List[Dict]:
             "url": data.get("html_url"),
         }]
 
-    except Exception as e:
-        if "429" in str(e) or "401" in str(e):
-            raise
+    except (RateLimitError, InvalidKeyError):
+        raise
+    except Exception:
         return []

package/osintkit/modules/stage2/hunter.py

@@ -4,6 +4,8 @@ from typing import Dict, List
 
 import httpx
 
+from osintkit.modules import RateLimitError, InvalidKeyError
+
 
 async def run(inputs: dict, api_key: str) -> List[Dict]:
     """Verify an email address via Hunter.io email-verifier endpoint.
@@ -30,9 +32,9 @@ async def run(inputs: dict, api_key: str) -> List[Dict]:
             )
 
         if response.status_code == 429:
-            raise Exception("429 rate limited")
+            raise RateLimitError("Hunter.io rate limit reached")
         if response.status_code in (401, 403):
-            raise Exception("401 invalid key")
+            raise InvalidKeyError("Hunter.io API key invalid or unauthorized")
 
         data = response.json()
         result = data.get("data", {})
@@ -58,7 +60,7 @@ async def run(inputs: dict, api_key: str) -> List[Dict]:
             "url": None,
         }]
 
-    except Exception as e:
-        if "429" in str(e) or "401" in str(e):
-            raise
+    except (RateLimitError, InvalidKeyError):
+        raise
+    except Exception:
         return []

package/osintkit/modules/stage2/leakcheck.py

@@ -4,6 +4,8 @@ from typing import Dict, List
 
 import httpx
 
+from osintkit.modules import RateLimitError, InvalidKeyError
+
 
 async def run(inputs: dict, api_key: str) -> List[Dict]:
     """Query LeakCheck.io for email breach records.
@@ -30,9 +32,9 @@ async def run(inputs: dict, api_key: str) -> List[Dict]:
             )
 
         if response.status_code == 429:
-            raise Exception("429 rate limited")
+            raise RateLimitError("LeakCheck rate limit reached")
         if response.status_code in (401, 403):
-            raise Exception("401 invalid key")
+            raise InvalidKeyError("LeakCheck API key invalid or unauthorized")
 
         data = response.json()
         if not data.get("success") or not data.get("result"):
@@ -52,7 +54,7 @@ async def run(inputs: dict, api_key: str) -> List[Dict]:
             })
         return findings
 
-    except Exception as e:
-        if "429" in str(e) or "401" in str(e):
-            raise
+    except (RateLimitError, InvalidKeyError):
+        raise
+    except Exception:
         return []

package/osintkit/modules/stage2/numverify.py

@@ -4,6 +4,8 @@ from typing import Dict, List
 
 import httpx
 
+from osintkit.modules import RateLimitError, InvalidKeyError
+
 
 async def run(inputs: dict, api_key: str) -> List[Dict]:
     """Validate a phone number via the NumVerify/apilayer API.
@@ -30,9 +32,9 @@ async def run(inputs: dict, api_key: str) -> List[Dict]:
             )
 
         if response.status_code == 429:
-            raise Exception("429 rate limited")
+            raise RateLimitError("NumVerify rate limit reached")
         if response.status_code in (401, 403):
-            raise Exception("401 invalid key")
+            raise InvalidKeyError("NumVerify API key invalid or unauthorized")
 
         data = response.json()
         if not data.get("valid") and data.get("error"):
@@ -56,7 +58,7 @@ async def run(inputs: dict, api_key: str) -> List[Dict]:
             "url": None,
         }]
 
-    except Exception as e:
-        if "429" in str(e) or "401" in str(e):
-            raise
+    except (RateLimitError, InvalidKeyError):
+        raise
+    except Exception:
         return []

package/osintkit/modules/stage2/securitytrails.py

@@ -4,6 +4,8 @@ from typing import Dict, List
 
 import httpx
 
+from osintkit.modules import RateLimitError, InvalidKeyError
+
 
 async def run(inputs: dict, api_key: str) -> List[Dict]:
     """Enumerate subdomains for the target's email domain via SecurityTrails API.
@@ -35,9 +37,9 @@ async def run(inputs: dict, api_key: str) -> List[Dict]:
             )
 
         if response.status_code == 429:
-            raise Exception("429 rate limited")
+            raise RateLimitError("SecurityTrails rate limit reached")
         if response.status_code in (401, 403):
-            raise Exception("401 invalid key")
+            raise InvalidKeyError("SecurityTrails API key invalid or unauthorized")
 
         data = response.json()
         subdomains = data.get("subdomains", [])
@@ -59,7 +61,7 @@ async def run(inputs: dict, api_key: str) -> List[Dict]:
             })
         return findings
 
-    except Exception as e:
-        if "429" in str(e) or "401" in str(e):
-            raise
+    except (RateLimitError, InvalidKeyError):
+        raise
+    except Exception:
         return []

package/osintkit/output/templates/report.html

@@ -3,72 +3,335 @@
 <head>
     <meta charset="UTF-8">
     <meta name="viewport" content="width=device-width, initial-scale=1.0">
-    <title>osintkit Report</title>
+    <title>osintkit Report — {{ inputs.name or inputs.email or inputs.username or 'Unknown' }}</title>
     <style>
-        body { font-family: system-ui, sans-serif; max-width: 800px; margin: 20px auto; padding: 20px; }
-        h1 { color: #333; border-bottom: 2px solid #ddd; padding-bottom: 10px; }
-        .risk-gauge { padding: 20px; border-radius: 8px; text-align: center; margin: 20px 0; }
-        .risk-high { background: #fee; color: #c00; }
-        .risk-medium { background: #ffe; color: #960; }
-        .risk-low { background: #efe; color: #060; }
-        .module-grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(200px, 1fr)); gap: 10px; margin: 20px 0; }
-        .module-card { padding: 15px; border: 1px solid #ddd; border-radius: 4px; }
-        .module-done { background: #efe; }
-        .module-failed { background: #fee; }
-        .module-skipped { background: #eee; color: #888; }
-        .findings-section { margin: 20px 0; }
-        .finding-item { padding: 10px; border-bottom: 1px solid #eee; }
+        * { box-sizing: border-box; margin: 0; padding: 0; }
+        body { font-family: system-ui, -apple-system, sans-serif; background: #f5f5f5; color: #222; }
+        .container { max-width: 900px; margin: 0 auto; padding: 30px 20px; }
+
+        /* Header */
+        .header { background: #1a1a2e; color: white; padding: 30px; border-radius: 10px; margin-bottom: 24px; }
+        .header h1 { font-size: 1.4rem; font-weight: 600; margin-bottom: 4px; opacity: 0.7; }
+        .header .target { font-size: 1.8rem; font-weight: 700; margin-bottom: 12px; }
+        .header .meta { font-size: 0.85rem; opacity: 0.6; }
+
+        /* Risk score */
+        .risk-block { border-radius: 10px; padding: 24px 30px; margin-bottom: 24px; display: flex; align-items: center; gap: 30px; }
+        .risk-high   { background: #fff0f0; border: 2px solid #e53e3e; }
+        .risk-medium { background: #fffbeb; border: 2px solid #d69e2e; }
+        .risk-low    { background: #f0fff4; border: 2px solid #38a169; }
+        .risk-score  { font-size: 3.5rem; font-weight: 800; line-height: 1; }
+        .risk-high   .risk-score  { color: #c53030; }
+        .risk-medium .risk-score  { color: #b7791f; }
+        .risk-low    .risk-score  { color: #276749; }
+        .risk-label  { font-size: 1.1rem; font-weight: 600; margin-bottom: 4px; }
+        .risk-desc   { font-size: 0.9rem; opacity: 0.8; max-width: 500px; }
+
+        /* Score bar */
+        .score-bar-wrap { flex: 1; }
+        .score-bar-bg   { background: #e2e8f0; border-radius: 999px; height: 12px; overflow: hidden; margin-top: 8px; }
+        .score-bar-fill { height: 100%; border-radius: 999px; transition: width 0.5s; }
+        .risk-high   .score-bar-fill { background: #e53e3e; }
+        .risk-medium .score-bar-fill { background: #d69e2e; }
+        .risk-low    .score-bar-fill { background: #38a169; }
+
+        /* Risk breakdown */
+        .breakdown { background: white; border-radius: 10px; padding: 20px 24px; margin-bottom: 24px; }
+        .breakdown h2 { font-size: 1rem; font-weight: 600; margin-bottom: 14px; color: #555; text-transform: uppercase; letter-spacing: 0.05em; }
+        .breakdown-grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(160px, 1fr)); gap: 12px; }
+        .breakdown-item { background: #f7f7f7; border-radius: 8px; padding: 12px; text-align: center; }
+        .breakdown-item .bi-val { font-size: 1.6rem; font-weight: 700; color: #2d3748; }
+        .breakdown-item .bi-label { font-size: 0.78rem; color: #718096; margin-top: 2px; }
+
+        /* Section card */
+        .card { background: white; border-radius: 10px; padding: 24px; margin-bottom: 20px; }
+        .card h2 { font-size: 1.05rem; font-weight: 700; margin-bottom: 16px; padding-bottom: 10px; border-bottom: 1px solid #eee; display: flex; align-items: center; gap: 8px; }
+        .badge { font-size: 0.75rem; padding: 2px 8px; border-radius: 999px; font-weight: 600; }
+        .badge-found  { background: #fed7d7; color: #c53030; }
+        .badge-none   { background: #e2e8f0; color: #4a5568; }
+        .badge-failed { background: #feebc8; color: #c05621; }
+
+        /* Finding items */
+        .finding { border: 1px solid #e2e8f0; border-radius: 8px; padding: 16px; margin-bottom: 12px; }
+        .finding-header { display: flex; align-items: flex-start; justify-content: space-between; gap: 12px; margin-bottom: 8px; }
+        .finding-type { font-weight: 600; font-size: 0.95rem; }
+        .finding-source { font-size: 0.8rem; color: #718096; background: #edf2f7; padding: 2px 8px; border-radius: 4px; white-space: nowrap; }
+        .finding-explanation { font-size: 0.88rem; color: #4a5568; margin-bottom: 10px; line-height: 1.5; }
+        .finding-data { background: #f7fafc; border-radius: 6px; padding: 10px 14px; font-size: 0.85rem; }
+        .finding-data table { width: 100%; border-collapse: collapse; }
+        .finding-data td { padding: 3px 8px 3px 0; vertical-align: top; }
+        .finding-data td:first-child { color: #718096; white-space: nowrap; padding-right: 16px; width: 1%; font-size: 0.82rem; }
+        .finding-data td a { color: #3182ce; word-break: break-all; }
+        .finding-url { margin-top: 8px; font-size: 0.85rem; }
+        .finding-url a { color: #3182ce; }
+
+        /* Module grid */
+        .module-grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(180px, 1fr)); gap: 10px; }
+        .module-card { border-radius: 8px; padding: 12px 14px; border: 1px solid transparent; }
+        .module-card .mc-name { font-weight: 600; font-size: 0.88rem; margin-bottom: 3px; }
+        .module-card .mc-detail { font-size: 0.8rem; opacity: 0.8; }
+        .mc-done    { background: #f0fff4; border-color: #9ae6b4; }
+        .mc-failed  { background: #fffaf0; border-color: #fbd38d; }
+        .mc-skipped { background: #f7fafc; border-color: #e2e8f0; color: #a0aec0; }
+
+        /* Recommendations */
+        .rec-item { display: flex; gap: 12px; padding: 14px 0; border-bottom: 1px solid #f0f0f0; }
+        .rec-item:last-child { border-bottom: none; }
+        .rec-icon { font-size: 1.3rem; flex-shrink: 0; margin-top: 1px; }
+        .rec-title { font-weight: 600; font-size: 0.92rem; margin-bottom: 3px; }
+        .rec-body  { font-size: 0.87rem; color: #4a5568; line-height: 1.5; }
+
+        /* Inputs summary */
+        .inputs-row { display: flex; flex-wrap: wrap; gap: 20px; }
+        .input-item .input-label { font-size: 0.78rem; color: #718096; text-transform: uppercase; letter-spacing: 0.05em; }
+        .input-item .input-val   { font-size: 0.95rem; font-weight: 500; }
+
+        .empty-state { color: #a0aec0; font-size: 0.9rem; text-align: center; padding: 20px; }
     </style>
 </head>
 <body>
-    <h1>osintkit OSINT Report</h1>
-    <p><strong>Scan Date:</strong> {{ scan_date }}</p>
-    <p><strong>Target:</strong> {{ inputs.name or inputs.email or inputs.username or inputs.phone or 'Unknown' }}</p>
-    
+<div class="container">
+
+    <!-- Header -->
+    <div class="header">
+        <h1>osintkit · OSINT Report</h1>
+        <div class="target">{{ inputs.name or inputs.email or inputs.username or inputs.phone or 'Unknown Target' }}</div>
+        <div class="meta">Scanned: {{ scan_date[:19]|replace('T', ' ') if scan_date else '—' }}</div>
+    </div>
+
+    <!-- Target info -->
+    <div class="card">
+        <h2>Target Information</h2>
+        <div class="inputs-row">
+            {% if inputs.name %}
+            <div class="input-item"><div class="input-label">Name</div><div class="input-val">{{ inputs.name }}</div></div>
+            {% endif %}
+            {% if inputs.email %}
+            <div class="input-item"><div class="input-label">Email</div><div class="input-val">{{ inputs.email }}</div></div>
+            {% endif %}
+            {% if inputs.username %}
+            <div class="input-item"><div class="input-label">Username</div><div class="input-val">{{ inputs.username }}</div></div>
+            {% endif %}
+            {% if inputs.phone %}
+            <div class="input-item"><div class="input-label">Phone</div><div class="input-val">{{ inputs.phone }}</div></div>
+            {% endif %}
+        </div>
+    </div>
+
+    <!-- Risk score -->
     {% set score = risk_score %}
     {% if score >= 70 %}
-        <div class="risk-gauge risk-high">
+        <div class="risk-block risk-high">
+        {% set risk_label = "High Risk" %}
+        {% set risk_desc = "Significant personal data is publicly exposed. Multiple findings across breaches, social media, and data brokers. Review and act on recommendations below." %}
     {% elif score >= 40 %}
-        <div class="risk-gauge risk-medium">
+        <div class="risk-block risk-medium">
+        {% set risk_label = "Medium Risk" %}
+        {% set risk_desc = "Some personal data is publicly accessible. A moderate digital footprint was found. Consider reviewing the findings and taking action on the most sensitive ones." %}
     {% else %}
-        <div class="risk-gauge risk-low">
+        <div class="risk-block risk-low">
+        {% set risk_label = "Low Risk" %}
+        {% set risk_desc = "Limited public exposure found. Your digital footprint appears small. Review any findings below to make sure nothing unexpected was discovered." %}
     {% endif %}
-        <h2>Risk Score: {{ score }}/100</h2>
+        <div>
+            <div class="risk-score">{{ score }}</div>
+            <div style="font-size:0.8rem;opacity:0.6;margin-top:2px;">out of 100</div>
+        </div>
+        <div style="flex:1">
+            <div class="risk-label">{{ risk_label }}</div>
+            <div class="risk-desc">{{ risk_desc }}</div>
+            <div class="score-bar-wrap">
+                <div class="score-bar-bg"><div class="score-bar-fill" style="width:{{ score }}%"></div></div>
+            </div>
+        </div>
     </div>
-    
-    <h2>Module Status</h2>
-    <div class="module-grid">
-        {% for module_name, module_data in modules.items() %}
-            <div class="module-card module-{{ module_data.status }}">
-                <strong>{{ module_name }}</strong><br>
-                {% if module_data.status == 'done' %}
-                    ✓ {{ module_data.count }} findings
-                {% elif module_data.status == 'failed' %}
-                    ✗ {{ module_data.error }}
-                {% else %}
-                    — skipped
-                {% endif %}
+
+    <!-- Score breakdown -->
+    {% set breach_count   = findings.get('breach_exposure', [])|length %}
+    {% set social_count   = (findings.get('social_profiles', [])|length) + (findings.get('sherlock', [])|length) %}
+    {% set broker_count   = findings.get('data_brokers', [])|length %}
+    {% set dark_count     = (findings.get('dark_web', [])|length) + (findings.get('paste_sites', [])|length) %}
+    {% set pw_count       = (findings.get('password_exposure', [])|length) + (findings.get('hibp_kanon', [])|length) %}
+    {% set total_findings = findings.values()|map('length')|sum %}
+
+    <div class="breakdown">
+        <h2>Score Breakdown</h2>
+        <div class="breakdown-grid">
+            <div class="breakdown-item">
+                <div class="bi-val">{{ total_findings }}</div>
+                <div class="bi-label">Total findings</div>
             </div>
-        {% endfor %}
+            <div class="breakdown-item">
+                <div class="bi-val">{{ breach_count }}</div>
+                <div class="bi-label">Data breaches</div>
+            </div>
+            <div class="breakdown-item">
+                <div class="bi-val">{{ social_count }}</div>
+                <div class="bi-label">Social profiles</div>
+            </div>
+            <div class="breakdown-item">
+                <div class="bi-val">{{ broker_count }}</div>
+                <div class="bi-label">Data broker listings</div>
+            </div>
+            <div class="breakdown-item">
+                <div class="bi-val">{{ dark_count }}</div>
+                <div class="bi-label">Dark web / paste sites</div>
+            </div>
+            <div class="breakdown-item">
+                <div class="bi-val">{{ pw_count }}</div>
+                <div class="bi-label">Password exposures</div>
+            </div>
+        </div>
     </div>
-    
-    <h2>Findings</h2>
+
+    <!-- Findings by module -->
+    {% set type_explanations = {
+        'social_profile':   'An account linked to this username was found on a public platform. This means the username is registered and potentially active there.',
+        'email_profile':    'This email address is linked to a public profile. Other people can potentially find your name, photo, or other info via this address.',
+        'email_account':    'This email was used to register on this platform. The registration is detectable without logging in.',
+        'password_exposure':'This email or password has appeared in a known data breach. If you reuse passwords, those accounts may be at risk.',
+        'breach':           'Your email or data was found in a breach database. The leaked data may include passwords, personal info, or other sensitive fields.',
+        'web_archive':      'A historical snapshot of content related to this target was found in web archives. Old pages may contain data you thought was deleted.',
+        'certificate':      'An SSL certificate was issued for a domain linked to this target. This can reveal subdomains, services, or infrastructure.',
+        'phone_info':       'Technical information about this phone number was retrieved. This includes carrier, region, and line type — without contacting the number.',
+        'paste':            'Content containing this target\'s data was found on a paste site. Paste sites are often used to dump leaked credentials or personal data.',
+        'dark_web':         'A reference to this target was found on a dark web index or public darknet search. This may indicate leaked data or illicit activity.',
+        'data_broker':      'This target appears in a data broker listing. Data brokers collect and sell personal information including name, address, and relatives.',
+        'web_presence':     'The email domain or username was found in web crawl data, subdomains, or public web content.',
+    } %}
+
     {% for module_name, module_findings in findings.items() %}
-        {% if module_findings %}
-            <div class="findings-section">
-                <h3>{{ module_name }} ({{ module_findings|length }})</h3>
-                {% for finding in module_findings %}
-                    <div class="finding-item">
-                        <strong>{{ finding.type }}</strong> 
-                        <span style="color:#888">via {{ finding.source }}</span>
-                        {% if finding.url %}
-                            <a href="{{ finding.url }}" target="_blank">[link]</a>
+    {% if module_findings %}
+    <div class="card">
+        <h2>
+            {{ module_name | replace('_', ' ') | title }}
+            <span class="badge badge-found">{{ module_findings|length }} found</span>
+        </h2>
+        {% for finding in module_findings %}
+        <div class="finding">
+            <div class="finding-header">
+                <div class="finding-type">{{ finding.type | replace('_', ' ') | title }}</div>
+                <div class="finding-source">via {{ finding.source }}</div>
+            </div>
+            {% if finding.type in type_explanations %}
+            <div class="finding-explanation">{{ type_explanations[finding.type] }}</div>
+            {% endif %}
+            {% if finding.data %}
+            <div class="finding-data">
+                <table>
+                {% for key, val in finding.data.items() %}
+                {% if val and val != '' and val != 'unknown' and key != 'note' %}
+                <tr>
+                    <td>{{ key | replace('_', ' ') }}</td>
+                    <td>
+                        {% if val is string and val.startswith('http') %}
+                            <a href="{{ val }}" target="_blank">{{ val }}</a>
+                        {% else %}
+                            {{ val }}
                         {% endif %}
-                        <br><small>Confidence: {{ finding.confidence }}</small>
-                    </div>
+                    </td>
+                </tr>
+                {% endif %}
                 {% endfor %}
+                {% if finding.data.get('note') %}
+                <tr><td colspan="2" style="color:#718096;font-style:italic;padding-top:6px;">{{ finding.data.note }}</td></tr>
+                {% endif %}
+                </table>
             </div>
-        {% endif %}
+            {% endif %}
+            {% if finding.url %}
+            <div class="finding-url">🔗 <a href="{{ finding.url }}" target="_blank">{{ finding.url }}</a></div>
+            {% endif %}
+        </div>
+        {% endfor %}
+    </div>
+    {% endif %}
     {% endfor %}
+
+    <!-- Recommendations -->
+    {% if total_findings > 0 %}
+    <div class="card">
+        <h2>What You Should Do</h2>
+        {% if pw_count > 0 %}
+        <div class="rec-item">
+            <div class="rec-icon">🔑</div>
+            <div>
+                <div class="rec-title">Change passwords for affected accounts</div>
+                <div class="rec-body">Your email appeared in one or more breach databases. Change the password for any account using this email, especially if you reuse passwords. Use a password manager to keep them unique.</div>
+            </div>
+        </div>
+        {% endif %}
+        {% if breach_count > 0 %}
+        <div class="rec-item">
+            <div class="rec-icon">🛡️</div>
+            <div>
+                <div class="rec-title">Enable two-factor authentication</div>
+                <div class="rec-body">Your data was found in breach records. Enable 2FA on your email, banking, and any other important accounts to prevent unauthorized access even if passwords are known.</div>
+            </div>
+        </div>
+        {% endif %}
+        {% if broker_count > 0 %}
+        <div class="rec-item">
+            <div class="rec-icon">🗑️</div>
+            <div>
+                <div class="rec-title">Request removal from data brokers</div>
+                <div class="rec-body">Your information appears in data broker listings. You can request removal directly from each broker. Services like DeleteMe or Incogni can automate this across hundreds of brokers.</div>
+            </div>
+        </div>
+        {% endif %}
+        {% if social_count > 0 %}
+        <div class="rec-item">
+            <div class="rec-icon">👤</div>
+            <div>
+                <div class="rec-title">Review your social media privacy settings</div>
+                <div class="rec-body">{{ social_count }} social profile(s) were found. Check the privacy settings on each platform — restrict who can see your posts, contact info, and friend/follower lists.</div>
+            </div>
+        </div>
+        {% endif %}
+        {% if dark_count > 0 %}
+        <div class="rec-item">
+            <div class="rec-icon">⚠️</div>
+            <div>
+                <div class="rec-title">Monitor for identity fraud</div>
+                <div class="rec-body">References to your data were found on dark web indexes or paste sites. Consider placing a credit freeze with the major credit bureaus and setting up identity monitoring alerts.</div>
+            </div>
+        </div>
+        {% endif %}
+        <div class="rec-item">
+            <div class="rec-icon">🔄</div>
+            <div>
+                <div class="rec-title">Re-scan periodically</div>
+                <div class="rec-body">Your digital footprint changes over time as new breaches occur and data spreads. Run <code>osintkit refresh</code> every few months to stay up to date.</div>
+            </div>
+        </div>
+    </div>
+    {% endif %}
+
+    <!-- Module status -->
+    <div class="card">
+        <h2>Modules Run</h2>
+        <div class="module-grid">
+            {% for module_name, module_data in modules.items() %}
+            <div class="module-card mc-{{ module_data.status }}">
+                <div class="mc-name">{{ module_name | replace('_', ' ') | title }}</div>
+                <div class="mc-detail">
+                    {% if module_data.status == 'done' %}
+                        ✓ {{ module_data.count }} finding{{ 's' if module_data.count != 1 else '' }}
+                    {% elif module_data.status == 'failed' %}
+                        ⚠ {{ module_data.error | truncate(40) }}
+                    {% else %}
+                        — skipped
+                    {% endif %}
+                </div>
+            </div>
+            {% endfor %}
+        </div>
+    </div>
+
+    <div style="text-align:center;color:#a0aec0;font-size:0.8rem;margin-top:20px;padding-bottom:20px;">
+        Generated by osintkit · Only use on targets you have permission to investigate · GDPR applies to EU subjects
+    </div>
+
+</div>
 </body>
 </html>

package/osintkit/scanner.py

@@ -8,6 +8,7 @@ from rich.console import Console
 from rich.progress import Progress
 
 from osintkit.config import Config
+from osintkit.modules import RateLimitError, InvalidKeyError
 from osintkit.output.json_writer import write_json
 from osintkit.output.html_writer import write_html
 from osintkit.output.md_writer import write_md
@@ -42,6 +43,7 @@ class Scanner:
             ("wayback", self._run_wayback, "Wayback Machine"),
             ("phone_info", self._run_phone_info, "Phone analysis"),
             ("hibp_kanon", self._run_hibp_kanon, "Password k-anonymity check"),
+            ("github_api", self._run_stage2_github, "GitHub profile"),  # always runs; token optional
         ]
 
         # Stage 2 modules — only included when corresponding API key is set
@@ -50,7 +52,6 @@ class Scanner:
             ("leakcheck", api_keys.leakcheck, self._run_stage2_leakcheck, "LeakCheck breach lookup"),
             ("hunter", api_keys.hunter, self._run_stage2_hunter, "Hunter email verify"),
             ("numverify", api_keys.numverify, self._run_stage2_numverify, "NumVerify phone"),
-            ("github_api", api_keys.github, self._run_stage2_github, "GitHub profile"),
             (
                 "securitytrails",
                 api_keys.securitytrails,
@@ -166,6 +167,12 @@ class Scanner:
                 result = await func(inputs)
                 findings["modules"][name] = {"status": "done", "count": len(result)}
                 findings["findings"][name] = result
+            except RateLimitError as e:
+                findings["modules"][name] = {"status": "rate_limited", "error": str(e)}
+                findings["findings"][name] = []
+            except InvalidKeyError as e:
+                findings["modules"][name] = {"status": "invalid_key", "error": str(e)}
+                findings["findings"][name] = []
             except Exception as e:
                 findings["modules"][name] = {"status": "failed", "error": str(e)}
                 findings["findings"][name] = []
@@ -203,13 +210,29 @@ class Scanner:
                     completed=True,
                     description=f"[green]done {task_info['desc']} ({len(result)})[/green]",
                 )
+            except RateLimitError as e:
+                findings["modules"][name] = {"status": "rate_limited", "error": str(e)}
+                findings["findings"][name] = []
+                progress.update(
+                    task_info["task_id"],
+                    completed=True,
+                    description=f"[yellow]rate limited {task_info['desc']}[/yellow]",
+                )
+            except InvalidKeyError as e:
+                findings["modules"][name] = {"status": "invalid_key", "error": str(e)}
+                findings["findings"][name] = []
+                progress.update(
+                    task_info["task_id"],
+                    completed=True,
+                    description=f"[yellow]invalid key {task_info['desc']}[/yellow]",
+                )
             except Exception as e:
                 findings["modules"][name] = {"status": "failed", "error": str(e)}
                 findings["findings"][name] = []
                 progress.update(
                     task_info["task_id"],
                     completed=True,
-                    description=f"[yellow]failed {task_info['desc']}[/yellow]",
+                    description=f"[red]failed {task_info['desc']}[/red]",
                 )
 
         async def main():

package/osintkit/setup.py

@@ -108,19 +108,29 @@ def run_setup_wizard():
             "google_cse_cx": "",
         }
     
-    # Save config
+    # Save config — merge with existing keys so we never wipe anything
     config_dir = Path.home() / ".osintkit"
     config_dir.mkdir(parents=True, exist_ok=True)
-    
-    config = {
-        "output_dir": "~/osint-results",
-        "timeout_seconds": 120,
-        "api_keys": api_keys,
-    }
-    
     config_path = config_dir / "config.yaml"
+
+    if config_path.exists():
+        with open(config_path) as f:
+            existing = yaml.safe_load(f) or {}
+        existing_keys = existing.get("api_keys", {})
+    else:
+        existing = {"output_dir": "~/osint-results", "timeout_seconds": 120}
+        existing_keys = {}
+
+    # Only overwrite keys the user actually provided (non-empty)
+    for k, v in api_keys.items():
+        if v:
+            existing_keys[k] = v
+        elif k not in existing_keys:
+            existing_keys[k] = ""
+
+    existing["api_keys"] = existing_keys
     with open(config_path, "w") as f:
-        yaml.dump(config, f, default_flow_style=False)
+        yaml.dump(existing, f, default_flow_style=False)
     config_path.chmod(0o600)  # owner read/write only — API keys must not be world-readable
 
     # Create profiles file
@@ -155,5 +165,6 @@ def update_api_key(key_name: str, key_value: str):
     
     with open(config_path, "w") as f:
         yaml.dump(config, f, default_flow_style=False)
-    
+    config_path.chmod(0o600)
+
     console.print(f"[green]✓[/green] Updated {key_name}")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "osintkit",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "OSINT CLI for personal digital footprint analysis",
   "bin": {
     "osintkit": "./bin/osintkit.js"
@@ -24,8 +24,16 @@
     "cli",
     "recon"
   ],
-  "author": "",
+  "author": "diesesschnitzel",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/diesesschnitzel/osintkit.git"
+  },
+  "homepage": "https://github.com/diesesschnitzel/osintkit#api-keys-all-optional",
+  "bugs": {
+    "url": "https://github.com/diesesschnitzel/osintkit/issues"
+  },
   "engines": {
     "node": ">=16",
     "python": ">=3.10"

package/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "osintkit"
-version = "0.1.4"
+version = "0.1.5"
 description = "OSINT CLI tool for personal digital footprint analysis"
 authors = ["Your Name <you@example.com>"]
 license = "MIT"