Bounty Bot

Autonomous GitHub issue validation engine for bug bounty programs

Architecture · API · Detection · Rules · Deployment · Configuration

---

Overview

Bounty Bot is the validation backbone for PlatformNetwork's bug bounty program. Every issue submitted to bounty-challenge is automatically ingested, scored through a multi-stage detection pipeline, and labeled with a verdict — all without human intervention.

Core principles

• LLM-assisted evaluation with deterministic rule enforcement.
• Zero-trust design: HMAC-signed inter-service calls, no hardcoded secrets.
• Extensible rules engine — drop a .ts file in rules/ and it's live.

---

How It Works

flowchart LR
subgraph Ingest
GH[GitHub Webhook]
POLL[Poller]
API[Atlas Command]
end
subgraph Validate["Validation Pipeline"]
direction TB
MEDIA[Media Check] --> SPAM[Spam Detection]
SPAM --> DUP[Duplicate Detection]
DUP --> EDIT[Edit History]
EDIT --> CODE["Code Rules\n(rules/code/)"]
CODE --> LLM["LLM Gate\n+ LLM Rules\n(rules/llm/)"]
end
subgraph Output
GH_MUT[GitHub Labels\n+ Comments]
ATLAS_CB[Atlas Callback]
DB[(SQLite)]
end
GH --> Validate
POLL --> Validate
API --> Validate
Validate --> GH_MUT
Validate --> ATLAS_CB
Validate --> DB

Loading

Each issue passes through six stages. A failure at any stage short-circuits to a verdict:

Stage	What it checks	Failure verdict
Media	Screenshot/video present and accessible (HTTP 200)	invalid
Spam	Template similarity, burst frequency, parity scoring	invalid
Duplicate	Jaccard + Qwen3 cosine hybrid (0.4J + 0.6C)	duplicate
Edit History	Suspicious post-submission edits (evidence swaps)	invalid
Code Rules	Programmatic checks from rules/code/*.ts	invalid or penalty
LLM Gate	Gemini 3.1 Pro + LLM instructions from rules/llm/*.ts	invalid

If all stages pass, the issue is labeled valid.

---

Quick Start

git clone https://github.com/PlatformNetwork/bounty-bot.git
cd bounty-bot
cp .env.example .env # fill in your tokens
npm install
npm run dev

Or with Docker:

docker compose up -d # starts bounty-bot + Redis + Watchtower

The API listens on port 3235. Watchtower auto-updates from GHCR every 60 seconds.

---

API

All /api/v1/* endpoints require HMAC authentication (X-Signature + X-Timestamp).

Method	Endpoint	Description
POST	/api/v1/validation/trigger	Trigger validation
GET	/api/v1/validation/:issue/status	Get verdict status
POST	/api/v1/validation/:issue/requeue	Re-validate (24h window)
POST	/api/v1/validation/:issue/force-release	Clear stale lock
GET	/api/v1/rules	List loaded rules
POST	/api/v1/rules/reload	Hot-reload rules from disk
GET	/health	Liveness probe

Full schemas and examples: docs/API.md

---

Rules Engine

Two kinds of rules, two directories:

rules/
code/ # Programmatic checks — executed by the engine
validity.ts # body length, title quality, structure
media.ts # evidence requirements
spam.ts # template detection, generic titles
content.ts # profanity, length limits, context
scoring.ts # penalty weight adjustments
llm/ # LLM instructions — injected into the prompt
evaluation.ts # evidence priority, reproducibility, confidence
tone.ts # professional tone, no sympathy verdicts
spam-detection.ts # template farming, AI filler, screenshot mismatch
output-format.ts # tool usage, reasoning order, no internal leaks

Code rules run programmatically and produce pass/fail results. They short-circuit the pipeline:

Severity	Effect
reject	Instant invalid verdict
require	Must pass or invalid
penalize	Adds weight to penalty score
flag	Logged but no verdict change

LLM rules are natural-language instructions injected into the model's system prompt, ordered by priority (critical > high > normal > low). They shape how the model reasons and phrases its verdict.

Hot-reload without restart: POST /api/v1/rules/reload

Full documentation: docs/RULES.md

---

LLM Integration

Two models via OpenRouter — both degrade gracefully if no API key is set.

Model	Purpose	Used in
google/gemini-3.1-pro-preview-customtools	Issue evaluation with function calling	deliver_verdict tool
qwen/qwen3-embedding-8b	Semantic duplicate detection	Cosine similarity vectors

The LLM receives pre-computed detection scores and rule evaluation results in its prompt, so rules directly influence the model's reasoning.

---

Testing

npm test# 149 tests (vitest)
npm run typecheck # tsc --noEmit
npm run lint # eslint

---

Documentation

Document	Description
Architecture	System design, module graph, sequence diagrams, database schema
API Reference	Full REST API with request/response schemas
Detection Engine	Spam, duplicate, edit-history, and LLM scoring internals
Rules Engine	How to write, load, and manage validation rules
Configuration	All environment variables and their defaults
Deployment	Docker, Redis, Watchtower, Atlas integration

---

Controlled by Atlas · Part of PlatformNetwork