COPS — Copilot Operations Plugins for Security

Welcome to COPS (Copilot Operations Plugins for Security)! COPS is an open-source, universal catalog of 25 defensive cybersecurity plugins, 27 specialist agent profiles, 37 canonical scenarios, and deterministic offline verification tools. The current registries reconcile these sources into 89 capabilities.

The AI asset inventory documents the bounded, offline evidence graph contract.

Start with Investigate possible malicious access for a complete case with malicious, benign, and insufficient-evidence outcomes. The runnable workflow index links every plugin's usage, design, schema reference, and checked playback.

The service attack notice registry provides a versioned, source-scoped offline assessment contract for service inventory and endpoint-validation evidence.

Use the plugin verification playbooks to test each package end to end, record qualification evidence, and update its maturity status after review.

Whether your team works in GitHub Copilot, Claude Code, or Codex / ChatGPT, COPS provides bounded, evidence-aware cybersecurity workflows without ecosystem lock-in. Everything is designed offline-first: you can explore tools, run demos, and validate detection logic directly from your local terminal using standard Python—no cloud credentials, assistant installations, or live tenant connections required.

📖 Visit the complete COPS Documentation Website for interactive guides, playbooks, and reference architectures.

---

Five-Minute Quickstart

Start with an ordinary-language goal, even if scope or evidence is incomplete. The getting-started guide separates drafting, local inspection, contract validation, and authorized execution.

The core commands require Python 3.11 or newer and use the Python standard library. Cloning the repository requires Git and network access; you can also use an existing local copy. After setup, the cops commands below run locally without external network calls:

# 1. Clone the repository and enter the directory
git clone https://github.com/sodejm/copilot-operation-plugin-for-security.git
cd copilot-operation-plugin-for-security

# 2. Check your local environment health
python3 -m cops doctor

# 3. List all 25 available security plugins and their status
python3 -m cops list

# 4. Recommend a specialist profile for a natural language task
python3 -m cops route "Optimize Microsoft Sentinel KQL query for sign-in anomalies"

# 5. Inspect details and operational playbooks for a plugin
python3 -m cops info sentinel-hunt-workbench

# 6. Run a safe, offline demonstration with synthetic data
python3 -m cops demo sentinel-hunt-workbench

# 7. Run the plugin's complete offline test suite
python3 -m cops check sentinel-hunt-workbench

Given an Engagement contract, you can resolve a narrow ordinary-language assessment request to an exact in-scope target:

python3 -m cops engagement goal \
  "Assess 10.100.0.10 for exposed services safely." \
  --engagement engagement.json \
  --json

The command accepts one exact target named directly in the request, or the engagement's recorded metadata.goal_selection.target when the request says "the selected endpoint". It rejects ambiguous, excluded, quoted, illustrative, and unsupported instructions, including targets beneath an excluded domain. After validating the contract, clarification responses include its ID and digest so the next request can be tied to the same version. Successful resolution retains the requested verb and contract digest while marking review and action binding as unverified. It reports needs_execution_path and not_assessed: no executable plan, approval, worker action, or recovery checkpoint is created. See Authenticated Execution for the current boundary and remaining work.

What these commands do for you

• cops doctor: Checks the Python version, catalog and package manifests, and generated marketplace indexes. It does not run plugins or audit their network behavior.
• cops list: Displays the 25 available security plugins, their maturity stage, and their validation status.
• cops route: Uses local keyword rules to recommend a specialist profile without an LLM or external API call. It does not launch an agent.
• cops demo: Runs a self-contained, offline walkthrough using synthetic test data.
• cops check: Executes deterministic verification suites (syntax checks, schema tests, mutation tests) right on your machine.
• cops engagement goal: Resolves a narrow request to one in-scope target and reports that execution is unavailable and coverage is not_assessed.

---

Available Security Plugins (25 Packages)

Each package lives in its own self-contained directory under plugins/<category>/<plugin-id>/ and includes a complete practitioner playbook:

Security Plugin	Category	Maturity	What it solves	Try it out
Security Logging Advisor	Logging & Telemetry	Stable	Audits codebases for security logging gaps, flags sensitive data leaks, and prioritizes CVE reachability.	python3 -m cops demo security-logging-advisor
Telemetry Proof Pack	Logging & Telemetry	Beta	Correlates supplied synthetic marker records across source, Cribl routing, destination, query, and alert stages.	python3 -m cops check telemetry-proof-pack
SOC Investigation Workbench	Detection & Hunting	Beta	Guides alert triage using competing hypotheses, question ranking, and evidence dependency graphs.	python3 -m cops demo soc-investigation-workbench
Sentinel Hunt Workbench	Detection & Hunting	Beta	Authors, adapts, and stress-tests 12 defensive Microsoft Sentinel and Defender KQL threat hunts offline.	python3 -m cops demo sentinel-hunt-workbench
Attack Path Workbench

For in-depth guidance on choosing the right plugin for your operational scenario, see the When to Use Each Plugin Guide.

---

27 Specialist Cybersecurity Agent Profiles & Dynamic Routing

COPS centralizes 27 specialist cybersecurity agent profiles in agents/ across offensive, defensive, forensics, identity, and governance disciplines. The six newest profiles route API security (cops-api-security-specialist), cloud posture (cops-cloud-posture-specialist), network segmentation (cops-network-segmentation-specialist), secrets remediation (cops-secrets-remediation-specialist), software supply chain and CI/CD (cops-supply-chain-specialist), and TLS and cryptography (cops-tls-crypto-specialist) work. The deterministic router uses local keyword rules to recommend a specialist profile:

# Route any security request or natural language task:
python3 -m cops route "Optimize this Sentinel KQL query for low ingestion cost"

# List all 27 specialist profiles:
python3 -m cops specialists

When the selected profile is marked critical, or you pass --critical, the router returns a proposed Triad Orchestration plan with a Primary Specialist, Domain Skeptic, Evidence Auditor, and handoff steps. It does not launch agents or execute the task. Read the Specialist Agents Guide for routing, handoff, and authorization boundaries.

Add --suggest-model --model-catalog model-catalog.json to receive offline model and reasoning-effort suggestions from fresh host evidence. Daybreak, Fable, Mythos, Astra, and other families qualify only through exact availability, access, capability, and effort records. See the model routing guide for catalog setup and the required preflight before implementing an issue.

---

MITRE ATT&CK & Attack Flow Coverage

COPS capability logic, queries, and investigation workflows are formally mapped to the MITRE ATT&CK Enterprise Matrix (pinned v18.0) and MITRE Attack Flow:

• MITRE ATT&CK Coverage Matrix: Explore normalized technique mappings, coverage roles, validation states, and known bypass confounders.
• Coverage & Attack Flow Guide: Gap analysis separating missing telemetry from missing analytics, representative STIX 2.1 Attack Flow exports, and authoring guidelines.

---

How Universal Portability Works

Different AI assistants expect different file structures, manifests, and skill formats. COPS generates host indexes from the catalog and checks for drift:

1. One Source of Truth: The central inventory in catalog/plugins.json defines all package metadata, versions, and categories.
2. Standardized Packages: Each plugin maintains its core Agent Plugins v1.0.0 manifest (plugin.json), host manifests (.claude-plugin/, .codex-plugin/), and reusable skills.
3. Automated Host Marketplaces: Running python3 -m cops generate automatically creates and synchronizes configuration files for:
   • GitHub Copilot: .github/plugin/marketplace.json
   • Claude Code: .claude-plugin/marketplace.json
   • Codex / ChatGPT: .agents/plugins/marketplace.json
4. Consistency Checks: Validation reports differences between the catalog and generated host indexes when the checks run.

Learn more in the Portability Architecture and Repository Layout guides.

---

Contributor Setup

To contribute new plugins, skills, or core features, install the test dependencies below. Installation requires network access unless you have prepared local packages; see the offline installation instructions.

# Set up a dedicated virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install development test dependencies
python3 -m pip install -r requirements.txt

# Run the complete test suite
make check-prerequisites
make check PYTHON=.venv/bin/python

(On Windows PowerShell, run .\.venv\Scripts\Activate.ps1 to activate your environment).

Before creating new plugins or modifying contracts, please review:

• Documentation Site: The official documentation website.
• Getting Started Guide: Quickstart and command walkthroughs.
• Authenticated Execution Guide: Configure verifier trust, immutable approval binding, one-time execution, migration, and key rotation.
• Service Validation Playbook: Route observed services, run the disposable loopback acceptance lab, and interpret evidence-bound validation states.
• Offline Research Execution: Provision and review the opt-in Linux profile for approved local corpora.
• AI Export Privacy Boundary: Versioned, field-aware policy boundary and caller-provided offline provider, telemetry, report, and diagnostic export adapters.
• Adding a Plugin: Step-by-step instructions for contributing a new security capability.
• Troubleshooting Guide: Solutions for common setup and dependency issues.
• Repository Contract (AGENTS.md): Coding conventions, git workflow, and branch rules.
• : Environment setup and testing workflows.

---

Evidence & Safety Principles

The opt-in aggregate assessment budget fixture records admission and recovery for synthetic assessment calls. It also mediates the Foundry Agent Harness's bundled offline provider-shaped response fixtures. Those fixtures use strict post-gate provider envelopes, hashed report case references, and a nonzero exit when the reported ledger is over budget. It does not mediate or attest real provider requests, usage, billing, cancellation, or cleanup.

In security engineering, confidence comes from verification:

• Offline Safety: Demos and checks run against local synthetic test data. They never make unreviewed network calls or write to remote production services.
• Clear Status Separation: We clearly separate what has been validated locally from what remains unverified in a live cloud environment. A passing offline test means its assertions passed for the tested cases. It does not prove all code correct, establish real attack coverage, or confirm that a production SIEM receives alerts.
• Data Privacy: Tools treat all input code and logs as sensitive data. They do not store credentials or transmit telemetry to third parties.
• Truth-in-Advertising: Capabilities are audited into five operational readiness modes (planned, guidance, import, laboratory, live-validated). Each claim requires evidence for its stated mode.
• Authenticated Execution Authority: High-consequence execution requires a signed full-plan snapshot, the expected worker identity, an active engagement, an independent verifier trust store, and an owner-provisioned worker capability inventory. See the Authenticated Execution Guide.
• AI Component Verification: Offline component identity, provenance and review-state reporting is documented in the AI Component Verification Guide; it never executes or fetches a component.

---

License & Attribution

• COPS project code and documentation are licensed under the PolyForm Noncommercial License 1.0.0.
• Reusable components imported from PARK retain their original Apache-2.0 notices. See Third-Party Notices and Licensing Guide for details.

Plugin execution cost analysis

Contributors can use plugin-run-cost to measure explicitly assigned COPS runs, estimate input scaling, and compare API, local-tool and employee costs. It runs locally with synthetic examples, preserves unknown charges, and distinguishes API-equivalent estimates from actual bills.

Local pre-push validation

See installation, prerequisites, security boundaries and recovery. CI remains required.

Offline EVTX import

cops telemetry import-evtx --input evidence.evtx --sha256 EXPECTED_SHA256 imports clean, non-wrapped EVTX exports through a pinned Linux parser. It supports Sysmon event IDs 1, 3, and 10 with content-free indicators and record evidence references. Missing or unsupported records remain partial. See the import contract and laboratory setup.

Raw forensic image integrity

cops forensic import --root evidence --manifest import.json verifies bounded raw disk and memory copies against their supplied digest and ordered custody records. It leaves originals unchanged and reports integrity separately from analysis. See formats, manifest fields, and limits.

Kubernetes containment playback

The isolated Kubernetes laboratory applies a NetworkPolicy to disposable pods, correlates HTTP and API audit telemetry, and verifies restored connectivity after success, failure and cancellation. Its pinned, privileged node requires a dedicated Linux lab host. The required laboratory gate includes this case; offline policy assessment alone cannot pass it.

CVE evidence binding

CVE workflow playback binds the pinned synthetic advisory to exact component versions and source digests. Its laboratory records actual vulnerable and corrected query calls. Missing or unrelated evidence remains insufficient; these fixtures do not establish production CVE coverage.

Consent remediation evidence

Consent workflow playback joins tenant-bound grants through service-principal IDs to application IDs in sign-ins. Missing, stale or conflicting evidence cannot produce a revocation target. The isolated lab revokes the exact synthetic grant and verifies that unrelated access survives.

Exposure audit evidence

Exposure workflow playback requires complete DNS, connection and authentication evidence for each scoped endpoint and collection window. Its isolated lab observes a fixed DNS answer and vulnerable/corrected HTTP responses. Missing or mismatched observations remain insufficient; external DNS discovery and production exposure validation require separate evidence.

Supply-chain installation evidence

The supply-chain laboratory installs hash-pinned synthetic wheels offline and exercises their vulnerable and corrected behavior through real HTTP requests. Tampered wheels must fail installation; missing dependency evidence stays unknown. Arbitrary package builds and production registries require separate adapters and validation.