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.

The collect command is your data-ingestion entry point. It queries the GitHub API for events on one or more repositories (or entire organizations) and writes raw payloads into PostgreSQL. Optional flags extend collection to GitHub Actions workflow runs, releases, contributor lists, workflow YAML files, and per-push commit metadata — each of which unlocks additional detection rules in analyze.

​
Usage

python cli.py collect [OPTIONS]

​
Options

​
--repos
string
Comma-separated list of repositories to collect from, in owner/repo format. When omitted, the tool falls back to the GITHUB_REPOS environment variable (or DEFAULT_REPOS in config.py). Either --repos or --orgs must be provided.
​
--orgs
string
Comma-separated list of GitHub organization names. Collects org-level events for every repository visible to your token. Can be combined with --repos to mix individual repositories and whole organizations in a single run.
​
--actions
boolean
default:"false"
Also collect GitHub Actions workflow run records for each specified repository. Populates the workflow_runs table, which is required by the workflow-run-from-fork and rapid-releases rules.
​
--releases
boolean
default:"false"
Also collect GitHub release events for each specified repository. Required to feed the release-actor-anomaly and rapid-releases analyzers.
​
--contributors
boolean
default:"false"
Seed the contributor list for each repository by calling the GitHub Contributors API. Storing known contributors as a baseline significantly improves the accuracy of the release-actor-anomaly rule by distinguishing established maintainers from first-time release actors.
​
--workflow-files
boolean
default:"false"
Fetch the raw YAML content of every workflow file (.github/workflows/*.yml) for each repository and store it in the workflow_files table. This data is consumed by static-analysis rules that search for unsafe ${{ github.event.* }} interpolations.
​
--commits
boolean
default:"false"
Fetch commit metadata for every push event on the default branch and store it in the push_commits table. Enables tamper-detection rules (commit-date-gap, null-committer-email) that compare commit timestamps and author fields against expected values.

​
Examples

Minimal — collect events for a single repository: 
python cli.py collect --repos aquasecurity/trivy
Full — collect all data types for multiple repositories: 
python cli.py collect \
  --repos aquasecurity/trivy,kubernetes/kubernetes \
  --actions \
  --releases \
  --contributors \
  --workflow-files \
  --commits
Org-level — collect events for every repository in an organization: 
python cli.py collect --orgs aquasecurity
--workflow-files must be passed at collection time to enable the ai-workflow-unsafe-input and issue-prompt-injection detection rules during analysis. Without it, workflow YAML content is not stored and those analyzers will produce no findings.Similarly, --commits is required to populate the commit metadata consumed by the commit-date-gap and null-committer-email tamper-detection rules.

​
Notes

  • collect calls apply_schema() automatically on startup, so it is safe to run before init-db has been called manually.
  • For org-level collection (--orgs), only top-level org events are fetched. To also collect Actions runs or releases for org repos, combine --orgs with --actions or --releases.
  • GitHub’s Events API returns up to 300 events per repository. For high-traffic repositories, schedule collect frequently (e.g., every 5–10 minutes via cron) to avoid missing events between polling intervals.

Build docs developers (and LLMs) love

Get started for freeTalk to us