Skip to content

About

Universal offline-first cybersecurity plugin catalog & 18 specialist AI agent profiles for GitHub Copilot, Claude Code, and Codex. Offline demos, MITRE ATT&CK v18.0, and deterministic verification.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

2 stars

Watchers

0 watching

Forks

Latest commit

 

History

389 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

COPS — Copilot Operations Plugins for Security

COPS shield and copilot visor logo

Documentation Site Python 3.11+ License Offline First MITRE ATT&CK v18.0 Universal Portability

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 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
AD Assessment Workbench Identity & Access Experimental Maps scoped Active Directory relationships and candidate paths from offline exports with explicit collection coverage. python3 -m cops demo ad-assessment-workbench
Secrets Remediation Workbench Identity & Access Experimental Builds redacted secret-incident records and reviewable revocation and rotation plans from imported evidence. python3 -m cops demo secrets-remediation-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
Exploit Validation Workbench Vulnerability Management Experimental Checks exact-version reproduction plans and local file digests offline; never authorizes or runs a proof. python3 -m cops demo exploit-validation-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
Cloud Posture Workbench Vulnerability Management Experimental Assesses imported infrastructure, Kubernetes, IAM, and cloud configuration evidence without connecting to a tenant. python3 -m cops demo cloud-posture-workbench
Supply Chain CI/CD Workbench Vulnerability Management Experimental Reviews imported lockfiles, SBOMs, workflow definitions, and provenance records for supply-chain risks. python3 -m cops demo supply-chain-cicd-workbench
Network Segmentation Workbench Vulnerability Management Experimental Evaluates imported policy, flow, DNS, packet, and reachability evidence against intended network boundaries. python3 -m cops demo network-segmentation-workbench
TLS and Crypto Workbench Vulnerability Management Experimental Reviews imported certificate, TLS, JWT, JWKS, and OpenSSL evidence with explicit provenance and coverage limits. python3 -m cops demo tls-crypto-workbench
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
Kubernetes Assessment Workbench Offensive Security Experimental Reconciles an approved Kubernetes context and namespace scope with a sanitized local observation. python3 -m cops demo kubernetes-assessment-workbench
Offensive Engagement Workbench Offensive Security Experimental Validates authorized engagement scope and prepares reviewable action plans from local inputs. python3 -m cops check offensive-engagement-workbench
Host Assessment Workbench Offensive Security Experimental Classifies local Linux and Windows privilege-boundary exports and imported canary reports without host execution. python3 -m cops demo host-assessment-workbench
Foundry Agent Harness Offensive Security Beta Rehearses synthetic agent/MCP authorization and provider response normalization with deterministic local fixtures. python3 -m cops check foundry-agent-harness
Web API Assessment Workbench Offensive Security Experimental Inventories and assesses imported HAR, OpenAPI, GraphQL, Postman, and gateway records through offline fixtures. python3 -m cops demo web-api-assessment-workbench
Incident Response Sandbox Incident Response Experimental Rehearses containment workflows, calculates blast radius, and generates cryptographic execution receipts. python3 -m cops check incident-response-sandbox
Compliance Posture Workbench Governance & Compliance Experimental Maps dated, versioned evidence to SOC 2, NIST, CIS, ISO, and PCI controls while preserving missing and stale states. python3 -m cops demo compliance-posture-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:


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

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.

About

Universal offline-first cybersecurity plugin catalog & 18 specialist AI agent profiles for GitHub Copilot, Claude Code, and Codex. Offline demos, MITRE ATT&CK v18.0, and deterministic verification.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

2 stars

Watchers

0 watching

Forks

Releases

Used by

Contributors

Languages