osintkit 0.1.3 → 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/bin/osintkit.js

@@ -1,42 +1,54 @@
 #!/usr/bin/env node
-const { spawn } = require('child_process');
+const { spawn, spawnSync } = require('child_process');
 const path = require('path');
 const fs = require('fs');
 
-// The npm package root is one level up from bin/
 const packageDir = path.dirname(path.dirname(__filename));
+const isWin = process.platform === 'win32';
+
+const venvPython = isWin
+    ? path.join(packageDir, '.venv', 'Scripts', 'python.exe')
+    : path.join(packageDir, '.venv', 'bin', 'python3');
+
+// If venv doesn't exist yet, run postinstall first (self-healing first run)
+if (!fs.existsSync(venvPython)) {
+    const postinstall = path.join(packageDir, 'postinstall.js');
+    if (fs.existsSync(postinstall)) {
+        console.log('osintkit: first run — setting up Python environment...');
+        const r = spawnSync(process.execPath, [postinstall], {
+            stdio: 'inherit',
+            cwd: packageDir,
+        });
+        if (!fs.existsSync(venvPython)) {
+            console.error('\nosintkit: setup failed. Run manually:');
+            console.error(`  node ${postinstall}`);
+            process.exit(1);
+        }
+    }
+}
 
-// Prefer venv Python (installed by postinstall), fall back to system Python.
-// Checks both Unix (.venv/bin/) and Windows (.venv/Scripts/) paths.
 function findPython() {
+    // Prefer venv Python (Unix + Windows)
     const venvCandidates = [
-        path.join(packageDir, '.venv', 'bin', 'python3'),        // Unix
-        path.join(packageDir, '.venv', 'bin', 'python'),          // Unix fallback
-        path.join(packageDir, '.venv', 'Scripts', 'python.exe'),  // Windows
-        path.join(packageDir, 'venv', 'bin', 'python3'),          // Unix alt name
-        path.join(packageDir, 'venv', 'bin', 'python'),           // Unix alt fallback
-        path.join(packageDir, 'venv', 'Scripts', 'python.exe'),   // Windows alt name
+        path.join(packageDir, '.venv', 'bin', 'python3'),
+        path.join(packageDir, '.venv', 'bin', 'python'),
+        path.join(packageDir, '.venv', 'Scripts', 'python.exe'),
+        path.join(packageDir, 'venv', 'bin', 'python3'),
+        path.join(packageDir, 'venv', 'Scripts', 'python.exe'),
     ];
     for (const p of venvCandidates) {
         if (fs.existsSync(p)) return p;
     }
-
     // Fall back to system Python
-    const systemCandidates = process.platform === 'win32'
-        ? ['python', 'python3']
-        : ['python3.11', 'python3', 'python'];
+    const systemCandidates = isWin ? ['python', 'python3'] : ['python3.11', 'python3', 'python'];
     for (const bin of systemCandidates) {
-        try {
-            require('child_process').execSync(`${bin} --version`, { stdio: 'ignore' });
-            return bin;
-        } catch (_) {}
+        const r = spawnSync(bin, ['--version'], { stdio: 'pipe' });
+        if (r.status === 0) return bin;
     }
     return 'python3';
 }
 
 const pythonBin = findPython();
-
-// Always set PYTHONPATH so the package is importable regardless of install method
 const env = {
     ...process.env,
     PYTHONPATH: process.env.PYTHONPATH

package/osintkit/__init__.py

@@ -1,3 +1,3 @@
 """osintkit - OSINT CLI tool for personal digital footprint analysis."""
 
-__version__ = "0.1.3"
+__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 []