Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/morwn/github-threat-detector/llms.txt

Use this file to discover all available pages before exploring further.

GitHub Threat Detector is configured entirely through environment variables, which can be supplied as shell exports or via a .env file in the project root. The variables fall into three groups: credentials and connection settings that are required for the tool to start, repository targeting that tells the collector which repositories to watch, and detection tuning knobs that control when the heuristic analyzers fire.

​
GitHub Personal Access Token Scopes

Before setting GITHUB_TOKEN you need a GitHub Personal Access Token (PAT) with the correct permission scopes. Without these the collector will receive 403 Forbidden responses from the API and no events will be stored.
ScopePurpose
repoRead events, commits, releases, and workflow files for private and public repositories
read:orgRead organization-level events when using --orgs during collection
Generate a classic PAT at GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic), then tick the repo and read:org scopes. Fine-grained PATs can also be used as long as “Repository: Read-only” access is granted for all targeted repositories.
Treat GITHUB_TOKEN like a password. Never commit it to source control or embed it in Docker images. Use a secrets manager, a CI/CD secret store, or at minimum a .env file that is listed in .gitignore.

​
Environment File Example

Copy this block into a .env file at the project root and fill in your values before running any CLI command:
.env
# --- Required ---
GITHUB_TOKEN=ghp_your_personal_access_token_here
DATABASE_URL=postgresql://postgres@localhost:5432/threat_detector
GITHUB_REPOS=aquasecurity/trivy,kubernetes/kubernetes

# --- Detection tuning ---
FORK_SPIKE_MULTIPLIER=3.0
FORK_SPIKE_WINDOW_DAYS=7
RAPID_PUSH_WINDOW_SECONDS=60
RAPID_PUSH_MIN_COUNT=5

# --- Advanced ---
GITHUB_API_BASE=https://api.github.com
REQUEST_TIMEOUT=30
MAX_PAGES=10

​
Required Variables

​
GITHUB_TOKEN
string
required
A GitHub Personal Access Token used to authenticate all API requests. Requires the repo and read:org scopes. Leaving this unset causes every API call to be made as an unauthenticated request, which is heavily rate-limited and will not return private repository data.
GITHUB_TOKEN=ghp_your_personal_access_token_here
​
DATABASE_URL
string
PostgreSQL connection string used by both the collector and the analyzer to read and write events and findings. The database and schema are created automatically the first time you run python cli.py init-db or any command that calls apply_schema.
DATABASE_URL=postgresql://postgres@localhost:5432/threat_detector
​
GITHUB_REPOS
string
default:""
Comma-separated list of repositories in owner/repo format that the collector targets by default. This value is used whenever --repos is not passed on the command line. Leave empty if you prefer always passing --repos explicitly.
GITHUB_REPOS=aquasecurity/trivy,kubernetes/kubernetes

​
Detection Tuning Variables

These variables control the sensitivity of the heuristic analyzers. Raising a multiplier or minimum count reduces false positives; lowering it makes detection more aggressive.
​
FORK_SPIKE_MULTIPLIER
float
default:"3.0"
The fork-spike analyzer triggers when the number of new forks in the rolling window exceeds the historical average multiplied by this value. Increase this number on repositories that naturally experience large fork surges (e.g., trending projects) to reduce noise.
FORK_SPIKE_MULTIPLIER=3.0
​
FORK_SPIKE_WINDOW_DAYS
integer
default:"7"
The length of the rolling window in days over which fork counts are aggregated before comparison against the historical average. A shorter window makes the detector more reactive to sudden spikes; a longer window smooths out bursty activity.
FORK_SPIKE_WINDOW_DAYS=7
​
RAPID_PUSH_WINDOW_SECONDS
integer
default:"60"
The time window in seconds used by the rapid-push analyzer to group push events. If the number of pushes within any window of this length meets or exceeds RAPID_PUSH_MIN_COUNT, a finding is generated.
RAPID_PUSH_WINDOW_SECONDS=60
​
RAPID_PUSH_MIN_COUNT
integer
default:"5"
The minimum number of push events that must occur within RAPID_PUSH_WINDOW_SECONDS to trigger a rapid-push finding. Raise this threshold for repositories with active CI pipelines that legitimately produce many pushes in quick succession.
RAPID_PUSH_MIN_COUNT=5

​
Advanced Variables

​
GITHUB_API_BASE
string
default:"https://api.github.com"
Base URL for all GitHub REST API requests. Override this when monitoring repositories hosted on a GitHub Enterprise Server instance.
GITHUB_API_BASE=https://github.example.com/api/v3
​
REQUEST_TIMEOUT
integer
default:"30"
Maximum time in seconds to wait for a response from the GitHub API before the request is aborted and retried. Increase this on slow or congested networks.
REQUEST_TIMEOUT=30
​
MAX_PAGES
integer
default:"10"
Maximum number of pages to fetch per paginated GitHub API request. Each page returns up to 100 items. Raising this limit allows the collector to ingest deeper history at the cost of more API quota consumption and longer collection runs.
MAX_PAGES=10
To monitor repositories on a GitHub Enterprise Server instance, set GITHUB_API_BASE to your server’s API root — for example https://github.example.com/api/v3. The PAT must be generated on that Enterprise instance, not on github.com.

Build docs developers (and LLMs) love

Get started for freeTalk to us