Connector Catalog

Two connectors are built into the core binary and driven directly by mallcop scan --connector: the GitHub org connector (--connector github) and the file/stdin connector (--connector file, the default). Six more cloud sources ship today as separate standalone binaries in the mallcop-connectors repo — they are not part of mallcop scan; you run the connector binary, capture its JSONL, and feed that file into mallcop scan --events (the two-step flow shown below). All connectors normalize events into the common schema below, and the core scanner applies the airlock before any event reaches the AI cascade.

GitHub · live

Pulls org events through a GitHub App. Captures membership changes, collaborator additions, and repo permission changes — the events the detector fleet reasons over.

Auth

Authenticate with a GitHub App installed on the org you want to monitor. The app needs read access to organization administration and audit events.

Usage

mallcop scan --connector github --github-org your-org-name --store ./store

Pass the connector and org as flags for a one-off run, or add them to mallcop.yaml once with mallcop config set connector --kind=github --id=<id> --org=<org> (see Configuration) so a bare mallcop scan picks it up — either way, put the command in a cron entry or a scheduled Action (see Quick Start) to run it on a schedule.

Event types

File / stdin · live

Read normalized events from a JSONL file or piped over stdin. Use this to bring your own exported logs, pipe events from any source, or replay history for testing.

Usage

mallcop scan --events events.jsonl --store ./store

# or pipe over stdin
cat events.jsonl | mallcop scan --events - --store ./store

Each line must conform to the common event schema below.

Cloud connectors · shipped (separate binaries)

These connectors ship today as standalone binaries in the mallcop-connectors repo — they are not built into mallcop scan. Each is its own single-purpose command that authenticates to its platform, pulls the audit/activity stream, normalizes it into the common event schema, and writes JSONL to stdout. It is a deliberate two-step flow: run the connector, redirect its output to a file, then feed that file into the core scanner with --events.

# install the AWS connector (its binary is named `aws`)
go install github.com/mallcop-app/mallcop-connectors/cmd/aws@latest

# step 1: pull CloudTrail events → JSONL on stdout, redirected to a file
aws --region us-east-1 --since 2026-01-01T00:00:00Z > events.jsonl

# step 2: feed that file into the built-in file connector
mallcop scan --events events.jsonl --store ./store

Each connector installs from cmd/<name> and its binary is named for that directory (aws, azure, gcp, github, m365, okta). They share a common flag set — --since <ISO-8601> to bound the window and --cursor to resume from a prior checkpoint — plus per-platform auth read from environment variables. See the mallcop-connectors README for each connector's exact flags and auth.

• aws — AWS CloudTrail: IAM, S3, Lambda, security group changes
• azure — Azure Activity Log: role assignments, Key Vault access, resource changes
• gcp — GCP Cloud Logging: admin activity, IAM, data access
• github — GitHub Audit Log stream (standalone counterpart to the built-in GitHub source)
• m365 — Microsoft 365 Management Activity: sign-ins, admin actions, Exchange mail rules
• okta — Okta System Log: authentications, MFA, admin and policy changes

Planned: first-class connector orchestration. Today only file and github are built into mallcop scan --connector; the cloud sources above run as the separate two-step flow. Driving these connectors directly from mallcop scan --connector aws (scheduling, checkpointing, and auth managed inside the core scan) is on the roadmap — it does not work yet. Until it lands, use the connector binary → --events two-step shown above.

Roadmap

The following connectors are not yet ported — planned standalone binaries, not available today:

• Container logs — parsed container/application log streams
• Vercel — deployment and access events
• Supabase — auth and database access events

Common event schema

All connectors emit events in a normalized format:

{
  "id": "evt-2026-03-11-github-abc123",
  "timestamp": "2026-03-11T14:00:00Z",
  "source": "github",
  "event_type": "collaborator_added",
  "actor": "[USER_DATA_BEGIN]octocat[USER_DATA_END]",
  "target": "[USER_DATA_BEGIN]acme-co/web[USER_DATA_END]",
  "action": "collaborator_added",
  "severity": "info",
  "metadata": {
    "permission": "write",
    "org": "acme-co"
  },
  "raw": "..."   <-- never exposed to the LLM
}

User-controllable string fields are wrapped in [USER_DATA_BEGIN]...[USER_DATA_END] markers at ingest. The raw field stores the original API response but is never included in actor context. See Security for the full airlock architecture.