Expand 39 api-reference stubs with real tool docs, expand 15 agent.py boilerplate stubs

skills/performing-dark-web-monitoring-for-threats/references/api-reference.md

@@ -1,27 +1,213 @@
-# API Reference: Dark web threat monitoring agent
+# API Reference: Dark Web Threat Monitoring
 
-## API Details
-Tor SOCKS proxy, paste site monitoring, credential leak detection, brand mention tracking
+## Libraries Used
+
+| Library | Purpose |
+|---------|---------|
+| `requests` | HTTP client for Tor-proxied requests and clearnet APIs |
+| `json` | Parse breach data and monitoring results |
+| `re` | Pattern matching for credentials and brand mentions |
+| `hashlib` | Hash credentials for safe lookup (k-anonymity) |
+| `datetime` | Track monitoring timelines |
 
 ## Installation
+
 ```bash
 pip install requests
+
+# Tor service (required for .onion access)
+# Ubuntu/Debian
+sudo apt install tor
+sudo systemctl start tor
+
+# macOS
+brew install tor && brew services start tor
 ```
 
-## Libraries
+## Authentication and Proxy Configuration
 
-| Library | Use |
-|---------|-----|
-| `requests` | requests |
+### Tor SOCKS5 Proxy Setup
+```python
+import requests
+import os
 
-## Authentication
+TOR_PROXY = os.environ.get("TOR_PROXY", "socks5h://127.0.0.1:9050")
+proxies = {"http": TOR_PROXY, "https": TOR_PROXY}
 
-| Method | Header |
-|--------|--------|
-| Bearer Token | `Authorization: Bearer <token>` |
-| API Key | `X-API-Key: <key>` |
+def tor_request(url, timeout=30):
+    """Make an HTTP request through the Tor network."""
+    resp = requests.get(url, proxies=proxies, timeout=timeout)
+    return resp
+```
+
+### Verify Tor Connectivity
+```python
+def check_tor_connection():
+    try:
+        resp = requests.get(
+            "https://check.torproject.org/api/ip",
+            proxies=proxies,
+            timeout=15,
+        )
+        data = resp.json()
+        return {"tor_active": data.get("IsTor", False), "exit_ip": data.get("IP")}
+    except requests.RequestException as e:
+        return {"tor_active": False, "error": str(e)}
+```
+
+## Credential Breach Monitoring
+
+### Have I Been Pwned API (k-Anonymity)
+```python
+import hashlib
+
+HIBP_API = "https://api.pwnedpasswords.com/range/"
+
+def check_password_breach(password):
+    """Check if a password appears in known breaches using k-anonymity."""
+    sha1 = hashlib.sha1(password.encode()).hexdigest().upper()
+    prefix = sha1[:5]
+    suffix = sha1[5:]
+
+    resp = requests.get(f"{HIBP_API}{prefix}", timeout=10)
+    resp.raise_for_status()
+
+    for line in resp.text.splitlines():
+        hash_suffix, count = line.split(":")
+        if hash_suffix == suffix:
+            return {"breached": True, "count": int(count)}
+    return {"breached": False, "count": 0}
+```
+
+### Check Email in Breaches
+```python
+HIBP_ACCOUNT_API = "https://haveibeenpwned.com/api/v3/breachedaccount/"
+
+def check_email_breaches(email, api_key):
+    """Check if an email appears in known data breaches."""
+    resp = requests.get(
+        f"{HIBP_ACCOUNT_API}{email}",
+        headers={
+            "hibp-api-key": api_key,
+            "user-agent": "SecurityAuditTool",
+        },
+        params={"truncateResponse": "false"},
+        timeout=15,
+    )
+    if resp.status_code == 200:
+        breaches = resp.json()
+        return {
+            "email": email,
+            "breached": True,
+            "breach_count": len(breaches),
+            "breaches": [
+                {
+                    "name": b["Name"],
+                    "date": b["BreachDate"],
+                    "data_classes": b["DataClasses"],
+                }
+                for b in breaches
+            ],
+        }
+    elif resp.status_code == 404:
+        return {"email": email, "breached": False, "breach_count": 0}
+    return {"email": email, "error": resp.status_code}
+```
+
+## Brand Mention Monitoring
+
+### Search Paste Sites
+```python
+def search_paste_sites(brand_keywords, api_key=None):
+    """Search paste monitoring services for brand mentions."""
+    findings = []
+    for keyword in brand_keywords:
+        # IntelligenceX API (example)
+        resp = requests.get(
+            "https://2.intelx.io/intelligent/search",
+            headers={"x-key": api_key} if api_key else {},
+            params={
+                "term": keyword,
+                "buckets": "pastes",
+                "maxresults": 20,
+                "datefrom": "",
+                "dateto": "",
+                "sort": 2,  # Date descending
+            },
+            timeout=30,
+        )
+        if resp.status_code == 200:
+            results = resp.json().get("records", [])
+            for r in results:
+                findings.append({
+                    "keyword": keyword,
+                    "source": r.get("systemid"),
+                    "date": r.get("date"),
+                    "bucket": r.get("bucket"),
+                })
+    return findings
+```
+
+## Domain Monitoring
+
+### Monitor for Credential Dumps Mentioning Domain
+```python
+def monitor_domain_mentions(domain, sources):
+    """Search for domain mentions across dark web sources."""
+    findings = []
+    email_pattern = re.compile(rf"[\w.+-]+@{re.escape(domain)}", re.IGNORECASE)
+
+    for source in sources:
+        try:
+            resp = tor_request(source["url"], timeout=30)
+            matches = email_pattern.findall(resp.text)
+            if matches:
+                findings.append({
+                    "source": source["name"],
+                    "emails_found": len(set(matches)),
+                    "sample": list(set(matches))[:5],
+                    "risk": "high",
+                })
+        except requests.RequestException:
+            continue
+    return findings
+```
+
+## Alerting
+
+```python
+def create_alert(finding, severity="high"):
+    return {
+        "alert_type": "dark_web_mention",
+        "severity": severity,
+        "source": finding.get("source"),
+        "detail": finding,
+        "timestamp": datetime.now().isoformat(),
+        "action_required": "Investigate and rotate exposed credentials",
+    }
+```
 
 ## Output Format
+
 ```json
-{"timestamp": "ISO-8601", "target": "URL", "findings": [], "risk_level": "HIGH"}
+{
+  "monitoring_date": "2025-01-15",
+  "domain": "example.com",
+  "tor_connected": true,
+  "credential_breaches": {
+    "emails_checked": 50,
+    "breached_accounts": 8,
+    "unique_breaches": 12
+  },
+  "paste_mentions": 3,
+  "dark_web_findings": [
+    {
+      "source": "paste-site",
+      "type": "credential_dump",
+      "emails_found": 15,
+      "risk": "high",
+      "action": "Force password reset for affected accounts"
+    }
+  ]
+}
 ```