mallcop
← Documentation

Quick Start Guide

From zero to automated security monitoring in under 10 minutes. Mallcop discovers your environment, learns what normal looks like, and tells you when something's off.

On this page

Choose install method Manual install Create deployment repo Azure setup Configure credentials Initialize Set up escalation Automate Actor chain Interactive investigation

Related

Configuration Connectors Actor System

Choose your install method

If you want automated setup, use one of the install paths at mallcop.app/install:

  • ClawCop — curl -sL mallcop.app/clawcop | sudo bash installs mallcop as a dedicated system user and schedules OpenClaw monitoring via cron. Linux or macOS, Python 3.10+, git, and OpenClaw required.

The rest of this guide covers manual installation with pip.

Install

Mallcop requires Python 3.11 or higher. No system dependencies.

pip install mallcop

Create a deployment repo

Mallcop stores all state - events, findings, baseline, config - as files in a git repo. This is the deployment repo. It's separate from mallcop's source code. You check it into version control. git log is your audit trail. 

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

Azure setup (if using Azure)

Mallcop needs a service principal with read-only access. Least privilege: Reader + Monitoring Reader + Log Analytics Reader. If you're comfortable with Claude Code, the quickest path is: 

# Tell Claude Code:
"Set up mallcop to monitor my Azure subscription."

# Claude Code will:
1. Create a deployment repo
2. Create service principal 'mallcop-monitor'
3. Assign least-privilege roles
4. Run mallcop init to discover your environment
5. Write mallcop.yaml and .env
6. Run first scan and detect

Or do it manually:

# Create service principal
az ad sp create-for-rbac --name mallcop-monitor \
  --role Reader \
  --scopes /subscriptions/<your-sub-id>

# Grant additional roles
SUB=/subscriptions/<your-sub-id>
az role assignment create --assignee <sp-client-id> \
  --role "Monitoring Reader" --scope $SUB
az role assignment create --assignee <sp-client-id> \
  --role "Log Analytics Reader" --scope $SUB

Configure credentials

Create a .env file in your deployment repo. Add it to .gitignore - never commit secrets. 

# .env (git-ignored)
AZURE_TENANT_ID=your-tenant-id
AZURE_CLIENT_ID=your-sp-client-id
AZURE_CLIENT_SECRET=your-sp-secret
ANTHROPIC_API_KEY=sk-ant-...        # or use managed inference
TEAMS_WEBHOOK_URL=https://...        # see escalation setup below

Initialize

mallcop init probes your environment, discovers connected platforms, and writes mallcop.yaml with estimated costs. 

$ mallcop init

Discovering environment...
  azure:  found (2 subscriptions, Activity Log accessible)
  github: found (6 repos, audit log accessible)
  vercel: found (3 projects, audit log accessible)

Wrote mallcop.yaml with 3 connectors configured.
Estimated appetite: ~110🍩/month
  Basic ($4.99, 150🍩) covers your setup.

How should Mallcop power its AI?
  [1] BYOK - Bring your own Anthropic API key
  [2] Mallcop Basic - $4.99/mo, managed inference (85% cheaper)
  [3] Mallcop Basic+ - $9.99/mo, adds investigations

Choice [1/2/3]:

Then run your first scan to verify everything is connected:

mallcop scan           # pull events from all connectors
mallcop detect         # run detectors (learning mode - informational only)
mallcop status --human # check everything looks right

The first 14 days are learning mode. Detectors flag findings as informational while mallcop builds a baseline. No alerts, no escalation. You're watching it learn.

Set up escalation

Mallcop validates that every finding has a path to a human. If escalation is broken, mallcop status tells you exactly what's wrong: 

ESCALATION: BROKEN
  Routing 'critical' → 'triage' → ... → channel 'notify-teams':
  webhook_url not configured

To set up a Teams webhook:

  1. In Teams, go to Workflows (hamburger menu)
  2. Search for "Post to a channel when a webhook request is received"
  3. Configure it and copy the URL
  4. Add to .env: TEAMS_WEBHOOK_URL=https://...

Verify: mallcop status --human should show Escalation: ok.

Slack and email channels are also supported. See the Actor System docs for configuration.

Automate with cron

Schedule mallcop watch (scan + detect + escalate) to run periodically. 

# Run every 6 hours
crontab -e
0 */6 * * *  cd /path/to/deployment-repo && mallcop watch && git add -A && git diff --cached --quiet || git commit -m "watch $(date -u +\%Y-\%m-\%dT\%H:\%M:\%SZ)" && git push

Events and findings commit back to your deployment repo on every run. git log events/ is your ingestion history.

How the actor chain works

When mallcop escalate runs (included in mallcop watch), findings flow through an actor chain:

# Typical flow for a warning-severity finding
Finding (severity: warn) → triage (Sonnet, read-only, 3 iterations)
  "Known contractor login during business hours → resolved"

Finding (severity: critical) → triage (Sonnet)
  "Unknown actor at 3 AM, can't determine intent → escalated"
  → investigate (Sonnet, read+write, 10 iterations)
    "Checked baseline, searched events, no match → escalated"
  → notify-teams (channel actor)
    POST to Teams webhook with batch digest

Triage resolves the obvious cases in one LLM call. Most findings never generate a notification. Cost is controlled by hard budget ceilings: per-finding token caps, per-run limits, and a circuit breaker that bypasses actors entirely during volume spikes.

Interactive investigation

When a finding reaches you, open Claude Code (or any AI agent) in your deployment repo:

cd my-security
claude

# Inside the session:
mallcop review                         # see all open findings
mallcop investigate <finding-id>       # deep context for one finding
mallcop events --finding <finding-id>  # raw events
mallcop baseline --actor baron@3dl.dev # what's normal for this actor
mallcop ack <id> "checked: expected"  # resolve + update baseline

mallcop review outputs everything an agent needs: the playbook, open findings grouped by severity, and suggested commands. The agent investigates, you confirm.