Welcome to COPS (Copilot Operations Plugins for Security)! COPS is an open-source, universal catalog of defensive cybersecurity plugins, 18 specialist agent profiles, and deterministic offline verification tools.
Whether your team works in GitHub Copilot, Claude Code, or Codex / ChatGPT, COPS provides production-grade cybersecurity capabilities 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.
All you need is Python 3.11 or newer. These commands use only the Python standard library and make zero 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 13 available security plugins and their status
python3 -m cops list
# 4. Route any natural language task to the best specialist agent
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-workbenchcops doctor: Quickly checks that your Python environment is ready and your package catalogs are in sync.cops list: Displays the thirteen available security plugins, their maturity stage, and their validation status.cops route: Deterministically routes any natural language task to the optimal specialist profile with zero LLM token cost.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.
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 | Verifies end-to-end telemetry routes and pipeline health from Cribl Stream to Splunk and Sentinel. | 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 | Detection & Hunting | Experimental | Traces multi-hop cloud lateral movement paths from local exports to crown jewels and finds choke points. | python3 -m cops demo attack-path-workbench |
| Detection Quality Workbench | Detection & Hunting | Beta | Validates detection syntax, regressions, and quality metrics across Microsoft Sentinel KQL and Splunk SPL. | python3 -m cops check detection-quality-workbench |
| Threat Intelligence Enrichment | Detection & Hunting | Experimental | Enriches network, host, and hash indicators with provenance-tracked threat intelligence metadata. | python3 -m cops check threat-intelligence-enrichment |
| Entra Identity Workbench | Identity & Access | Beta | Evaluates Entra ID role assignments, service principals, consent grants, and credential exposures. | python3 -m cops check entra-identity-workbench |
| Exposure Triage Workbench | Vulnerability Management | Beta | Prioritizes vulnerability triage by correlating advisory CVEs, SBOM components, and call graph reachability. | python3 -m cops check exposure-triage-workbench |
| Patch Security Review | Vulnerability Management | Beta | Analyzes code patches and pull request diffs for dangerous patterns, authorization flaws, and regression risks. | python3 -m cops check patch-security-review |
| Attack Surface Planner | Offensive Security | Experimental | Translates authorized rules of engagement into bounded, passive review plans from local export manifests. | python3 -m cops demo attack-surface-planner |
| Foundry Agent Harness | Offensive Security | Beta | Evaluates AI agent behavior, prompt injection resistance, and safety boundaries in a simulated sandbox. | python3 -m cops check foundry-agent-harness |
| Incident Response Sandbox | Incident Response | Beta | Rehearses containment workflows, calculates blast radius, and generates cryptographic execution receipts. | python3 -m cops check incident-response-sandbox |
For in-depth guidance on choosing the right plugin for your operational scenario, see the When to Use Each Plugin Guide.
COPS centralizes 18 specialist cybersecurity agent profiles in agents/ across offensive, defensive, forensics, identity, and governance disciplines. The deterministic zero-token router dynamically matches incoming tasks to the best 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 18 specialist profiles:
python3 -m cops specialistsFor high-risk operations (e.g. penetration testing, red team emulation, active containment, or cloud privilege escalation), COPS automatically activates Triad Orchestration (Primary Specialist + Domain Skeptic + Evidence Auditor) with mandatory interactive operator authorization. Read the Specialist Agents Guide for architecture details.
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.
Different AI assistants expect different file structures, manifests, and skill formats. COPS removes that headache through automated, drift-free synchronization:
- One Source of Truth: The central inventory in
catalog/plugins.jsondefines all package metadata, versions, and categories. - Standardized Packages: Each plugin maintains its core Agent Plugins v1.0.0 manifest (
plugin.json), host manifests (.claude-plugin/,.codex-plugin/), and reusable skills. - Automated Host Marketplaces: Running
python3 -m cops generateautomatically creates and synchronizes configuration files for:- GitHub Copilot:
.github/plugin/marketplace.json - Claude Code:
.claude-plugin/marketplace.json - Codex / ChatGPT:
.agents/plugins/marketplace.json
- GitHub Copilot:
- Guaranteed Consistency: Our test gates verify that host indexes never drift out of sync with the catalog.
Learn more in the Portability Architecture and Repository Layout guides.
If you want to contribute new plugins, skills, or core features:
# 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.
- 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.
- Contributing Guide: Environment setup and testing workflows.
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 proves code correctness—it does not claim your production SIEM is currently receiving live 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 four operational readiness modes (
planned,import,laboratory,live-validated), with zero false live claims.
- 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.
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.