Open-source ecosystems are increasingly targeted by adversaries who compromise maintainer accounts, inject malicious code through CI/CD pipelines, tamper with release artifacts, and manipulate repository workflows — often weeks before anyone notices. GitHub Threat Detector is a Python CLI tool that continuously collects GitHub API events into PostgreSQL and runs a battery of heuristic analyzers to surface these threats before they reach your users.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.
What It Detects
Supply chain attacks rarely announce themselves. GitHub Threat Detector watches for the subtle signals that precede and accompany a compromise: a first-time actor pushing a workflow change, a release published by an account that has never shipped a release before, apull_request_target workflow firing from an untrusted fork, or AI-workflow YAML that accepts unsanitized issue body input. Fifteen detection rules across six attack categories give you broad coverage of the modern GitHub threat surface.
| Category | Rules |
|---|---|
| Malicious CI/CD | workflow-file-change, pr-target-abuse, workflow-run-from-fork |
| Release Tampering | release-actor-anomaly, rapid-releases |
| Social Engineering | new-actor-ci-change, member-added-suspicious, repo-made-public |
| Repository Abuse | fork-spike |
| Push Anomalies | force-push-default, rapid-sequential-pushes, delete-branch-protection |
| AI Workflow Abuse | issue-prompt-injection, issue-rapid-close, ai-workflow-unsafe-input |
| Commit Tampering | commit-date-gap, null-committer-email |
GitHub Threat Detector was directly inspired by real-world supply chain incidents, including the 2023 compromise of the aquasecurity/trivy ecosystem and similar attacks against popular open-source projects where malicious actors gained brief but sufficient repository access to tamper with release workflows or inject backdoors into CI pipelines.
The Three-Phase Pipeline
GitHub Threat Detector operates in three explicit, independently runnable phases, giving you full control over data freshness and analysis cadence. 1. Collect — thecollect command polls the GitHub Events API (and optionally the Actions, Releases, Contributors, Workflow Files, and Commits APIs) for one or more repositories or organizations, deduplicates results, and writes raw event records to PostgreSQL.
2. Analyze — the analyze command loads all collected events and runs every enabled heuristic analyzer against them. Each analyzer produces zero or more findings — structured records that include a rule ID, severity, actor, repository, and human-readable description — which are also persisted to PostgreSQL.
3. Report — the report command queries the findings table and renders results as a Rich terminal table or JSON, with filtering by severity, repository, and time window.
Requirements
- Python 3.10+ — the codebase uses
X | Yunion type hints andmatchexpressions - PostgreSQL — findings and raw events are stored relationally;
psycopg2-binaryis the only required driver - GitHub Personal Access Token — needs
repoandread:orgscopes to access private repository events and organization membership data
Get Started
Quickstart
Clone the repo, configure your environment, and run your first threat scan in five steps.
CLI Reference
Full reference for all
collect, analyze, report, and init-db options and flags.Detectors Overview
Deep-dive into all 15 detection rules, their severity ratings, and the attack patterns they surface.