@harbinger-ai/harbinger 0.1.0

package/agents/report-writer/TOOLS.md

@@ -0,0 +1,69 @@
+Primary: markdown, pandoc, mermaid (diagrams), screenshot tools, video recording, HTML/PDF templates, HackerOne API, Bugcrowd API, Intigriti API. Each with usage examples.
+
+### Usage Examples:
+
+**markdown**
+```bash
+# Markdown is a markup language, not a command-line tool itself.
+# It's used for writing content, which can then be processed by other tools.
+# Example: A simple markdown file content
+# # My Report\n\nThis is a **test** report.
+```
+
+**pandoc**
+```bash
+pandoc input.md -o output.pdf
+```
+
+**mermaid (diagrams)**
+```bash
+# Mermaid is a JavaScript-based diagramming tool. It's typically integrated into markdown renderers or web applications.
+# Example of Mermaid syntax within a markdown file:
+# ```mermaid
+# graph TD;
+#     A-->B;
+#     A-->C;
+#     B-->D;
+#     C-->D;
+# ```
+```
+
+**screenshot tools**
+```bash
+# Example using scrot (a common Linux screenshot tool)
+scrot -s -o screenshot.png
+```
+
+**video recording**
+```bash
+# Example using ffmpeg (a powerful multimedia tool)
+ffmpeg -f x11grab -s 1920x1080 -i :0.0 -c:v libx264 -preset ultrafast -crf 23 output.mp4
+```
+
+**HTML/PDF templates**
+```bash
+# These are typically files used by other tools (like pandoc or custom scripts) for rendering.
+# Example: Using a custom HTML template with pandoc
+pandoc input.md -o output.html --template=custom_template.html
+```
+
+**HackerOne API**
+```bash
+# Interacting with HackerOne API typically involves making HTTP requests with an API key.
+# Example using curl (conceptual, actual API calls vary):
+curl -X GET -H "X-Auth-Token: YOUR_API_TOKEN" https://api.hackerone.com/v1/reports
+```
+
+**Bugcrowd API**
+```bash
+# Interacting with Bugcrowd API typically involves making HTTP requests with an API key.
+# Example using curl (conceptual, actual API calls vary):
+curl -X GET -H "Authorization: Token token=YOUR_API_TOKEN" https://api.bugcrowd.com/v3/submissions
+```
+
+**Intigriti API**
+```bash
+# Interacting with Intigriti API typically involves making HTTP requests with an API key.
+# Example using curl (conceptual, actual API calls vary):
+curl -X GET -H "Authorization: Bearer YOUR_API_TOKEN" https://api.intigriti.com/v1/submissions
+```

package/agents/shared/README.md

@@ -0,0 +1,13 @@
+# Shared Agent Infrastructure
+
+The runtime implementations for agent infrastructure live in the main package:
+
+| Feature | Location | Description |
+|---------|----------|-------------|
+| **Model Router** | `lib/ai/model-router.js` | SmartModelRouter — complexity-based model selection |
+| **Autonomous Engine** | `lib/ai/autonomous-engine.js` | Background thinking loop (enabled via `AUTONOMOUS_THINKING=true`) |
+| **Agent Discovery** | `lib/agents.js` | Discovers and loads agent profiles from `agents/` directories |
+| **Agent Runtime** | `lib/ai/agent.js` | LangGraph agent with tool use and memory checkpointing |
+
+Agent profiles in `agents/{name}/` provide identity, personality, and skill documentation.
+The runtime code in `lib/` provides the actual execution engine.

package/agents/web-hacker/CONFIG.yaml

@@ -0,0 +1,24 @@
+model: configurable
+temperature: 0.7 # creative
+docker_image: harbinger/web-hacker
+proxy_chain: configurable
+max_concurrent_tests: 5
+payload_wordlists: configurable
+auto_handoff: true
+handoff_to: [report-writer]
+receives_from: [recon-scout]
+
+# Resource limits (enforced by Docker)
+memory_mb: 4096
+cpu_count: 4
+
+# Agent capabilities
+capabilities:
+  - xss_testing
+  - sqli_testing
+  - ssrf_testing
+  - idor_testing
+  - fuzzing
+  - nuclei_scanning
+  - parameter_discovery
+  - authentication_bypass

package/agents/web-hacker/HEARTBEAT.md

@@ -0,0 +1,78 @@
+# BREACH — Heartbeat Protocol
+
+## Heartbeat Schedule
+
+- **Interval:** Every 60 seconds while active
+- **Endpoint:** `POST /api/agents/{{agent_id}}/heartbeat`
+- **Model:** Cheapest available (Haiku or Gemini Flash)
+- **Cost target:** < $0.005 per heartbeat
+
+## Health Check Tasks
+
+### 1. Self-Check
+- [ ] Process alive and responsive
+- [ ] Workspace accessible (`/workspace` and `/workspace/wordlists`)
+- [ ] Primary tools functional (spot-check: `nuclei -version`, `sqlmap --version`)
+- [ ] Memory within 4096MB limit
+- [ ] Network accessible (targets and Harbinger API reachable)
+- [ ] Nuclei templates up to date
+- [ ] Wordlists accessible and intact
+
+### 2. Test Status
+- [ ] Test currently running? Report tool, target, progress
+- [ ] Targets tested vs total count
+- [ ] Vulnerabilities found by severity (critical/high/medium/low/info)
+- [ ] Any test stalled? (no output in 5 minutes)
+- [ ] Pending targets from PATHFINDER
+- [ ] Findings handed off to SCRIBE
+
+### 3. Swarm Health
+- [ ] Message bus reachable (`/api/agents/broadcast`)
+- [ ] PATHFINDER feeding targets (last received timestamp)
+- [ ] SCRIBE available for report handoff
+- [ ] Shared context accessible
+
+### 4. Container Health
+- [ ] Sub-containers (parallel scanners) running
+- [ ] Disk usage within limits
+- [ ] No zombie processes from crashed tools
+- [ ] Caido proxy accessible
+
+## Response Format
+
+**Active testing:**
+```json
+{
+  "status": "busy",
+  "current_task": "xss_testing",
+  "target": "https://target.com/search",
+  "progress": 45,
+  "vulns_found": {"critical": 0, "high": 1, "medium": 3, "low": 2, "info": 5},
+  "targets_tested": 12,
+  "targets_total": 30,
+  "healthy": true
+}
+```
+
+**Idle:**
+```json
+{"status": "idle", "current_task": null, "progress": 0, "healthy": true}
+```
+
+**Issues:**
+```json
+{
+  "status": "error",
+  "current_task": "sqli_testing",
+  "progress": 60,
+  "healthy": false,
+  "issues": ["sqlmap crashed on target X", "nuclei templates outdated 7 days"]
+}
+```
+
+## Escalation
+
+1. **Unresponsive (3 missed):** Orchestrator logs warning, probes container
+2. **Critical (5 missed):** Orchestrator restarts container, preserves findings
+3. **Tool crash:** Log error, attempt restart, notify operator if persistent
+4. **Persistent failure:** Remove from active pool, create incident

package/agents/web-hacker/IDENTITY.md

@@ -0,0 +1 @@
+Name: Web Hacker. Codename: BREACH. Role: Web application vulnerability discovery and exploitation. Specialization: injection attacks, authentication bypasses, business logic flaws, API security, client-side attacks.

package/agents/web-hacker/SKILLS.md

@@ -0,0 +1 @@
+OWASP Top 10 exploitation, API fuzzing techniques, authentication bypass patterns, business logic testing methodology, WAF bypass techniques, chained vulnerability exploitation.

package/agents/web-hacker/SOUL.md

@@ -0,0 +1,23 @@
+Personality: Creative, persistent, thinks laterally. Loves finding the weird edge cases nobody else checks. Communication style: confident, explains attack chains step by step. Thinks like a lockpick artist. Motto: "Every input is a door."
+
+## Meta-Cognition — Autonomous Thinking
+
+### Self-Awareness
+- Monitor exploit attempt success rate, payload effectiveness, and WAF bypass ratio
+- Track which vulnerability classes yield the most findings per target (XSS, SQLi, SSRF, IDOR)
+- Evaluate time-per-finding to optimize scan configs for maximum impact
+
+### Enhancement Identification
+- Detect repetitive injection patterns that could become nuclei templates
+- Evaluate model tier: use fast models for fuzzing, reserve reasoning models for complex chain construction
+- Identify when manual testing should yield to automated scanning and vice versa
+
+### Efficiency Tracking
+- Formula: COST_BENEFIT = (TIME_SAVED x FREQUENCY) / (IMPL_COST + RUNNING_COST)
+- Only propose automations where cost_benefit > 1.0
+- Track: vulns per hour, unique CVEs triggered, duplicate finding rate
+
+### Swarm Awareness
+- Read swarm state to see what PATHFINDER has discovered before testing
+- Announce confirmed vulnerabilities for SCRIBE to document immediately
+- Auto-handoff cloud misconfigs to PHANTOM, binary issues to CIPHER

package/agents/web-hacker/TOOLS.md

@@ -0,0 +1,86 @@
+Primary: nuclei, sqlmap, dalfox, ffuf, feroxbuster, burpsuite, xsstrike, nosqlmap, ssrfmap, commix, tplmap, jwt_tool, arjun, paramspider, corstest, dirsearch. Each with usage examples.
+
+### Usage Examples:
+
+**nuclei**
+```bash
+nuclei -u https://example.com -t cves/
+```
+
+**sqlmap**
+```bash
+sqlmap -u "http://example.com/vuln?id=1" --batch
+```
+
+**dalfox**
+```bash
+dalfox url https://example.com
+```
+
+**ffuf**
+```bash
+ffuf -w /path/to/wordlist.txt -u https://example.com/FUZZ
+```
+
+**feroxbuster**
+```bash
+feroxbuster -u https://example.com
+```
+
+**burpsuite**
+```bash
+# Burp Suite is a GUI tool, typically used interactively.
+# Command line usage is for specific integrations or headless scans.
+# Example for headless scan (requires Burp Suite Professional and API setup):
+java -jar burpsuite_pro.jar --project-file=project.burp --headless.mode=scan --url=https://example.com
+```
+
+**xsstrike**
+```bash
+xsstrike -u "https://example.com/search?q=test"
+```
+
+**nosqlmap**
+```bash
+nosqlmap -u "http://example.com/api/v1/user" --data "{'username':'admin'}"
+```
+
+**ssrfmap**
+```bash
+ssrfmap -r request.txt -p "url"
+```
+
+**commix**
+```bash
+commix -u "http://example.com/cmd?input=test"
+```
+
+**tplmap**
+```bash
+tplmap -u "http://example.com/template?name=test"
+```
+
+**jwt_tool**
+```bash
+jwt_tool -t eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c -X a
+```
+
+**arjun**
+```bash
+arjun -u https://example.com/api/v1/users
+```
+
+**paramspider**
+```bash
+paramspider -d example.com
+```
+
+**corstest**
+```bash
+corstest -u https://example.com
+```
+
+**dirsearch**
+```bash
+dirsearch -u https://example.com -e php,html,js
+```

package/api/CLAUDE.md

@@ -0,0 +1,19 @@
+# /api — External API Routes
+
+This directory contains the route handlers for all `/api/*` endpoints. These routes are for **external callers only** — GitHub Actions, Telegram, cURL, third-party webhooks.
+
+## Auth
+
+All routes (except `/telegram/webhook` and `/github/webhook`, which use their own webhook secrets) require a valid API key passed via the `x-api-key` header. API keys are stored in the SQLite database and managed through the admin UI — they are NOT environment variables.
+
+Auth flow: `x-api-key` header -> `verifyApiKey()` -> database lookup (hashed, timing-safe comparison).
+
+## Do NOT use these routes for browser UI
+
+Browser-facing features must use **Server Actions** (`'use server'` functions) with `requireAuth()` session checks — never `/api` fetch calls. The only exception is chat streaming, which has its own dedicated route at `/stream/chat` with session auth.
+
+| Caller | Mechanism | Auth |
+|--------|-----------|------|
+| External (cURL, GitHub Actions, Telegram) | `/api` route | `x-api-key` header |
+| Browser UI (data/mutations) | Server Action | `requireAuth()` session |
+| Browser UI (chat streaming) | `/stream/chat` | `auth()` session |

package/api/index.js

@@ -0,0 +1,274 @@
+import { createHash, timingSafeEqual } from 'crypto';
+import { createJob } from '../lib/tools/create-job.js';
+import { setWebhook } from '../lib/tools/telegram.js';
+import { getJobStatus, fetchJobLog } from '../lib/tools/github.js';
+import { getTelegramAdapter } from '../lib/channels/index.js';
+import { chat, summarizeJob } from '../lib/ai/index.js';
+import { createNotification } from '../lib/db/notifications.js';
+import { loadTriggers } from '../lib/triggers.js';
+import { verifyApiKey } from '../lib/db/api-keys.js';
+
+// Bot token from env, can be overridden by /telegram/register
+let telegramBotToken = null;
+
+// Cached trigger firing function (initialized on first request)
+let _fireTriggers = null;
+
+function getTelegramBotToken() {
+  if (!telegramBotToken) {
+    telegramBotToken = process.env.TELEGRAM_BOT_TOKEN || null;
+  }
+  return telegramBotToken;
+}
+
+function getFireTriggers() {
+  if (!_fireTriggers) {
+    const result = loadTriggers();
+    _fireTriggers = result.fireTriggers;
+  }
+  return _fireTriggers;
+}
+
+// Routes that have their own authentication
+const PUBLIC_ROUTES = ['/telegram/webhook', '/github/webhook', '/ping', '/health'];
+
+/**
+ * Timing-safe string comparison.
+ * @param {string} a
+ * @param {string} b
+ * @returns {boolean}
+ */
+function safeCompare(a, b) {
+  if (!a || !b) return false;
+  const bufA = Buffer.from(a);
+  const bufB = Buffer.from(b);
+  if (bufA.length !== bufB.length) return false;
+  return timingSafeEqual(bufA, bufB);
+}
+
+/**
+ * Centralized auth gate for all API routes.
+ * Public routes pass through; everything else requires a valid API key from the database.
+ * @param {string} routePath - The route path
+ * @param {Request} request - The incoming request
+ * @returns {Response|null} - Error response or null if authorized
+ */
+function checkAuth(routePath, request) {
+  if (PUBLIC_ROUTES.includes(routePath)) return null;
+
+  const apiKey = request.headers.get('x-api-key');
+  if (!apiKey) {
+    return Response.json({ error: 'Unauthorized' }, { status: 401 });
+  }
+
+  const record = verifyApiKey(apiKey);
+  if (!record) {
+    return Response.json({ error: 'Unauthorized' }, { status: 401 });
+  }
+
+  return null;
+}
+
+/**
+ * Extract job ID from branch name (e.g., "job/abc123" -> "abc123")
+ */
+function extractJobId(branchName) {
+  if (!branchName || !branchName.startsWith('job/')) return null;
+  return branchName.slice(4);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Route handlers
+// ─────────────────────────────────────────────────────────────────────────────
+
+async function handleWebhook(request) {
+  const body = await request.json();
+  const { job } = body;
+  if (!job) return Response.json({ error: 'Missing job field' }, { status: 400 });
+
+  try {
+    const result = await createJob(job);
+    return Response.json(result);
+  } catch (err) {
+    console.error(err);
+    return Response.json({ error: 'Failed to create job' }, { status: 500 });
+  }
+}
+
+async function handleTelegramRegister(request) {
+  const body = await request.json();
+  const { bot_token, webhook_url } = body;
+  if (!bot_token || !webhook_url) {
+    return Response.json({ error: 'Missing bot_token or webhook_url' }, { status: 400 });
+  }
+
+  try {
+    const result = await setWebhook(bot_token, webhook_url, process.env.TELEGRAM_WEBHOOK_SECRET);
+    telegramBotToken = bot_token;
+    return Response.json({ success: true, result });
+  } catch (err) {
+    console.error(err);
+    return Response.json({ error: 'Failed to register webhook' }, { status: 500 });
+  }
+}
+
+async function handleTelegramWebhook(request) {
+  const botToken = getTelegramBotToken();
+  if (!botToken) return Response.json({ ok: true });
+
+  const adapter = getTelegramAdapter(botToken);
+  const normalized = await adapter.receive(request);
+  if (!normalized) return Response.json({ ok: true });
+
+  // Process message asynchronously (don't block the webhook response)
+  processChannelMessage(adapter, normalized).catch((err) => {
+    console.error('Failed to process message:', err);
+  });
+
+  return Response.json({ ok: true });
+}
+
+/**
+ * Process a normalized message through the AI layer with channel UX.
+ * Message persistence is handled centrally by the AI layer.
+ */
+async function processChannelMessage(adapter, normalized) {
+  await adapter.acknowledge(normalized.metadata);
+  const stopIndicator = adapter.startProcessingIndicator(normalized.metadata);
+
+  try {
+    const response = await chat(
+      normalized.threadId,
+      normalized.text,
+      normalized.attachments,
+      { userId: 'telegram', chatTitle: 'Telegram' }
+    );
+    await adapter.sendResponse(normalized.threadId, response, normalized.metadata);
+  } catch (err) {
+    console.error('Failed to process message with AI:', err);
+    await adapter
+      .sendResponse(
+        normalized.threadId,
+        'Sorry, I encountered an error processing your message.',
+        normalized.metadata
+      )
+      .catch(() => {});
+  } finally {
+    stopIndicator();
+  }
+}
+
+async function handleGithubWebhook(request) {
+  const { GH_WEBHOOK_SECRET } = process.env;
+
+  // Validate webhook secret (timing-safe, required)
+  if (!GH_WEBHOOK_SECRET || !safeCompare(request.headers.get('x-github-webhook-secret-token'), GH_WEBHOOK_SECRET)) {
+    return Response.json({ error: 'Unauthorized' }, { status: 401 });
+  }
+
+  const payload = await request.json();
+  const jobId = payload.job_id || extractJobId(payload.branch);
+  if (!jobId) return Response.json({ ok: true, skipped: true, reason: 'not a job' });
+
+  try {
+    // Fetch log from repo via API (no longer sent in payload)
+    let log = payload.log || '';
+    if (!log) {
+      log = await fetchJobLog(jobId, payload.commit_sha);
+    }
+
+    const results = {
+      job: payload.job || '',
+      pr_url: payload.pr_url || payload.run_url || '',
+      run_url: payload.run_url || '',
+      status: payload.status || '',
+      merge_result: payload.merge_result || '',
+      log,
+      changed_files: payload.changed_files || [],
+      commit_message: payload.commit_message || '',
+    };
+
+    const message = await summarizeJob(results);
+    await createNotification(message, payload);
+
+    console.log(`Notification saved for job ${jobId.slice(0, 8)}`);
+
+    return Response.json({ ok: true, notified: true });
+  } catch (err) {
+    console.error('Failed to process GitHub webhook:', err);
+    return Response.json({ error: 'Failed to process webhook' }, { status: 500 });
+  }
+}
+
+async function handleJobStatus(request) {
+  try {
+    const url = new URL(request.url);
+    const jobId = url.searchParams.get('job_id');
+    const result = await getJobStatus(jobId);
+    return Response.json(result);
+  } catch (err) {
+    console.error('Failed to get job status:', err);
+    return Response.json({ error: 'Failed to get job status' }, { status: 500 });
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Next.js Route Handlers (catch-all)
+// ─────────────────────────────────────────────────────────────────────────────
+
+async function POST(request) {
+  const url = new URL(request.url);
+  const routePath = url.pathname.replace(/^\/api/, '');
+
+  // Auth check
+  const authError = checkAuth(routePath, request);
+  if (authError) return authError;
+
+  // Fire triggers (non-blocking)
+  try {
+    const fireTriggers = getFireTriggers();
+    // Clone request to read body for triggers without consuming it for the handler
+    const clonedRequest = request.clone();
+    const body = await clonedRequest.json().catch(() => ({}));
+    const query = Object.fromEntries(url.searchParams);
+    const headers = Object.fromEntries(request.headers);
+    fireTriggers(routePath, body, query, headers);
+  } catch (e) {
+    // Trigger errors are non-fatal
+  }
+
+  // Route to handler
+  switch (routePath) {
+    case '/create-job':          return handleWebhook(request);
+    case '/telegram/webhook':   return handleTelegramWebhook(request);
+    case '/telegram/register':  return handleTelegramRegister(request);
+    case '/github/webhook':     return handleGithubWebhook(request);
+    case '/mcp': { const { handleMcpRequest } = await import('../lib/mcp/handler.js'); return handleMcpRequest(request); }
+    default:                    return Response.json({ error: 'Not found' }, { status: 404 });
+  }
+}
+
+async function GET(request) {
+  const url = new URL(request.url);
+  const routePath = url.pathname.replace(/^\/api/, '');
+
+  // Auth check
+  const authError = checkAuth(routePath, request);
+  if (authError) return authError;
+
+  switch (routePath) {
+    case '/ping':           return Response.json({ message: 'Pong!' });
+    case '/health': {
+      const checks = { status: 'ok', timestamp: new Date().toISOString() };
+      try { const { getDb } = await import('../lib/db/index.js'); getDb(); checks.database = 'ok'; } catch { checks.database = 'error'; checks.status = 'degraded'; }
+      try { const { discoverAgents } = await import('../lib/agents.js'); checks.agents = discoverAgents().length; } catch { checks.agents = 0; }
+      checks.env = { GH_TOKEN: !!process.env.GH_TOKEN, GH_OWNER: !!process.env.GH_OWNER, GH_REPO: !!process.env.GH_REPO };
+      return Response.json(checks);
+    }
+    case '/jobs/status':    return handleJobStatus(request);
+    case '/mcp': { const { handleMcpRequest } = await import('../lib/mcp/handler.js'); return handleMcpRequest(request); }
+    default:                return Response.json({ error: 'Not found' }, { status: 404 });
+  }
+}
+
+export { GET, POST };