mallcop
← Documentation

Quick Start Guide

From zero to security monitoring in a few minutes. Install the Go binary, point mallcop at your GitHub org, and let mallcop scan learn what normal looks like.

On this page

Install Create a store repo GitHub setup Initialize First scan Automate with cron Review findings

Related

Configuration Connectors CLI

Install

mallcop is a single Go binary — no Python, no runtime dependency. Install with the Go toolchain:

go install github.com/mallcop-app/mallcop/cmd/mallcop@latest

Or download a prebuilt release binary from GitHub Releases and put it on your PATH. See Install for all options.

Create a store repo

mallcop stores all state — events, findings, resolutions, baseline, config — as files in a git repo you control. This is the git-native store. git log is your audit trail. 

mkdir my-security && cd my-security
git init

Or skip the manual steps below entirely: mallcop init --create-repo owner/name scaffolds a deployment repo (go.mod pin, detectors/, connectors/, and a scheduled .github/workflows/scan.yml Action) and creates + pushes it to GitHub for you — the fastest path to continuous monitoring with no cron to babysit. See CLI Reference § init for the flag details.

GitHub setup

The live GitHub connector reads org events through a GitHub App. Install a GitHub App on the org you want to monitor with read access to organization administration and audit events, then export its credentials as environment variables: 

export GITHUB_APP_ID=...
export GITHUB_APP_PRIVATE_KEY=...       # the app's private key (PEM)
export GITHUB_INSTALLATION_ID=...

Your inference endpoint and key (for the AI cascade) are read from the environment too. Bring your own vendor key and mallcop costs you $0; or point at the mallcop endpoint with a mallcop-sk-* key for managed inference: 

export MALLCOP_INFERENCE_URL=https://api.anthropic.com   # your vendor (BYOK), or https://api.mallcop.app
export MALLCOP_API_KEY=...                             # your vendor key, or a mallcop-sk-* key

With no inference URL set, mallcop still runs — every finding force-escalates to you (the documented fail-safe), no key required.

Initialize

mallcop init scaffolds mallcop.yaml — the one file mallcop reads — plus a store/ directory and a sample events.jsonl, then prints the exact next-step commands. mallcop.yaml is the primary, zero-flag config path; the environment variables above still work and take precedence over it for any value you set explicitly. 

$ mallcop init

mallcop init: created <dir>/mallcop.yaml (config — offline inference)
mallcop init: created <dir>/store/ (findings store)
mallcop init: created <dir>/events.jsonl (sample events)

Next steps:
  1. Run the scan (reads mallcop.yaml — no flags needed):
       mallcop scan
  2. Add a source: edit mallcop.yaml -> connectors:
     (a github org, or a cloud source like aws/azure)
  3. For managed LLM resolution (offline is the fail-safe default):
       mallcop init --pro  &&  export MALLCOP_API_KEY=mallcop-sk-...

First scan

mallcop scan runs the full pipeline end to end: connect → detect → triage → investigate → committee consensus, writing findings and resolutions to the git store you pass with --store (required). 

mallcop scan --connector github --github-org YOUR_ORG --store store
mallcop status --store store   # check events and findings counts

The first days are learning mode. Detection is baseline-relative, so mallcop spends the early scans building a picture of your normal before flagging anomalies with full severity.

Automate with cron

There's no daemon and no mallcop watch — continuous monitoring is just mallcop scan on a schedule you control. If you used mallcop init --create-repo above, the scheduled GitHub Action it scaffolded already does this — nothing further to set up. Running it yourself, commit the store after each run for a clean history: 

# crontab -e — run every 6 hours
0 */6 * * *  cd /path/to/my-security && mallcop scan --connector github --github-org YOUR_ORG --store store && git -C store add -A && git -C store diff --cached --quiet || git -C store commit -m "scan $(date -u +\%Y-\%m-\%dT\%H:\%M:\%SZ)"

Events, findings, and resolutions commit back to your store on every run. git log is your ingestion and decision history.

Review findings

Findings and their full reasoning live in the git store. Read them, and when you rule on one with mallcop feedback, that ruling is written back to the store as a suppress directive the next scan honors — so mallcop stops re-flagging what you've already cleared. 

mallcop status --store store                 # counts by source and status
git -C store log                            # every event, finding, and resolution, in order

# rule on a finding — "silence" a known-good class
mallcop feedback <finding_id> dismiss --store store --reason "known onboarding"

The hosted mallcop.app chat is the same loop in a browser: it reads findings.jsonl from your repo, answers grounded questions about them, and writes the same suppress directives back over a GitOps commit. Either way, the next scan reads the directive and suppresses the finding.