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 init-db command applies the full database schema to the configured PostgreSQL instance by calling apply_schema(). It creates every table needed by the collect, analyze, and report commands in a single step. Running init-db before any other command is the recommended way to prepare a fresh environment, though it is never strictly required — all other commands apply the schema automatically on startup.

​
Usage

python cli.py init-db
This command takes no options. On success it prints: 
Schema applied.

​
Tables Created

init-db ensures the following tables exist. All CREATE TABLE statements use IF NOT EXISTS, so the command is safe to re-run at any time.

​
github_events

Stores raw GitHub API event payloads as they are returned by the Events API. Every row written by collect lands here first. Analyzers read from this table to detect patterns across push, pull-request, member, public, delete, and other event types.
github_events is not defined in schema.sql and is therefore not created by init-db. It must already exist before init-db is run (for example, created by a separate migration). The findings table references github_events(id) as a foreign key, so the database will reject apply_schema() if github_events does not exist.

​
workflow_runs

Holds GitHub Actions workflow run records collected when collect --actions is passed. Used by the workflow-run-from-fork and rapid-releases rules to detect CI abuse and abnormal release cadences.

​
workflow_files

Stores the raw YAML content of workflow files fetched by collect --workflow-files. Static analysis rules (ai-workflow-unsafe-input, issue-prompt-injection) scan this content for unsafe ${{ github.event.* }} interpolations that could allow AI prompt injection via untrusted input.

​
repo_contributors

Contains contributor records seeded by collect --contributors. Rules such as release-actor-anomaly compare release actors against this baseline to identify whether a release was published by someone outside the established contributor set.

​
push_commits

Stores commit metadata for default-branch pushes collected by collect --commits. The commit-date-gap and null-committer-email tamper-detection rules query this table to identify commits with implausible timestamps or missing committer email fields.

​
findings

The output table written by analyze. Each row represents a single threat finding and includes:
  • id — auto-incremented primary key
  • rule_id — the rule that produced the finding
  • severity — one of critical, high, medium, low
  • repo_name — the affected repository in owner/repo format
  • actor_login — GitHub username of the actor involved
  • event_id — originating GitHub API event ID
  • description — human-readable summary
  • evidence — rule-specific JSONB object with supporting detail
  • created_at — timestamp of when the finding was recorded

​
Example

python cli.py init-db

Schema applied.
init-db is fully idempotent. Every CREATE TABLE statement uses IF NOT EXISTS, so running the command against an already-initialized database is harmless — no data is modified or dropped.You do not need to call init-db manually before running collect, analyze, or report — each of those commands invokes apply_schema() automatically on startup. init-db exists as a convenience for environment setup scripts, Docker entrypoints, and CI pipelines that need an explicit schema-initialization step.

Build docs developers (and LLMs) love

Get started for freeTalk to us