| name | orca-compliance-gap |
| description | Deep-dive compliance gap analysis for any framework — failing controls ranked by impact, quick wins, account breakdown, and remediation plan. Use when user asks about compliance gaps, failures, or status (e.g., "compliance gaps", "PCI DSS status", "where are we failing", "SOC 2 compliance", "quick wins"). |
| trigger | When user asks about compliance gaps, framework scores, failing controls, compliance posture, "how's our PCI compliance", "what's failing in SOC 2", "compliance gap analysis", "show me compliance issues", or framework-specific questions (e.g., "CIS benchmark gaps", "NIST failures") |
Orca Compliance Gap Skill
Answers the question: "Where are we failing, what's the fastest path to improve, and who owns the worst gaps?"
Given a compliance framework (or all frameworks), analyzes failing controls ranked by blast radius, identifies quick wins (single-fix controls), breaks down gaps by account/business unit, and generates a prioritized remediation plan.
Usage
/orca-compliance-gap
/orca-compliance-gap PCI DSS
/orca-compliance-gap CIS AWS
/orca-compliance-gap SOC 2
Or natural language:
- "how's our PCI compliance?"
- "what's failing in CIS AWS?"
- "compliance gap analysis"
- "show me our worst compliance gaps"
- "which framework needs the most work?"
- "quick wins for SOC 2"
Processing Logic
Step 1: Determine Scope
Parse user input to determine:
- Specific framework: "PCI DSS" → filter to that framework
- All frameworks: no argument → show overview of all, then drill into worst
- Account-specific: "compliance in account 123456789012" → filter by account
Step 2: Gather Data (run ALL in parallel)
Query 1: All enabled frameworks with current scores
get_enabled_compliance_frameworks:
(no filters)
Query 2: Compliance trend over time
get_compliance_trend_over_time:
filters:
datetime_filter: 30
Query 3: Compliance by account
get_compliance_analysis_by_account_or_business_unit:
group_by: "accounts"
Query 4: Compliance by business unit
get_compliance_analysis_by_account_or_business_unit:
group_by: "business_units"
Step 3: Deep-Dive into Target Framework(s)
For the target framework (or the worst-scoring one if user said "all"), run Queries 5-8 in parallel. Query 6 depends on Query 5 (it needs the rule_ids), so run it after Query 5 returns.
Query 5: Failing control tests
get_compliance_framework_control_tests:
framework_id: <id>
filters:
status: "fail"
Query 6: Compliant + non-compliant assets per failing control (runs after Query 5)
Scope to the top N failing controls (default N=5) to keep response sizes manageable. The rule_id comes from Query 5's tests[].rule_id.
get_control_test_assets:
framework_id: <id>
rule_id: <tests[].rule_id from Query 5> # one call per top-N failing control
Returns { non_compliant_assets: [...], compliant_assets: [...] } — both arrays, so true pass/fail ratios are computable per control, not just a failure count.
Query 7: Framework stats
get_compliance_framework_stats_for_asset:
framework_id: <id>
Query 8: Assets with most failures
get_framework_assets_with_failed_controls_count:
framework_id: <id>
Query 9: Per-framework account breakdown
get_compliance_analysis_by_account_or_business_unit:
group_by: "accounts"
framework_ids: ["<framework_id>"]
Step 4: Analyze and Rank
Quick Win Detection
A "quick win" is a failing control where:
- Few assets are affected — use the actual
non_compliant_assets.length from Query 6 (get_control_test_assets), not a guess (treat < 5 as low)
- The fix is a single configuration change (not architectural)
- Fixing it passes the control completely (no partial pass)
- The control appears in multiple frameworks (high ROI)
Impact Ranking
Rank failing controls by:
- Cross-framework impact — for the top failing assets returned by Query 6 (
get_control_test_assets), call get_related_compliance_frameworks_for_asset with the asset's group_unique_id as asset_unique_id. A control/asset participating in more frameworks gets priority.
- HARD RULE: before counting frameworks per asset, filter
result[] to entries where active === true. The result array includes frameworks with active: false (frameworks that could apply to this asset type but aren't enabled in the tenant). Counting them inflates cross-framework impact with frameworks the customer hasn't enabled.
- Asset count — controls failing on many assets = systematic issue
- Severity — critical/high controls before medium/low
- Fix complexity — simple config changes before architectural changes
Account Responsibility
Map failing controls to accounts to identify:
- Which account drags the score down most
- Which account has the most unique failures
- Cross-account patterns (same control failing everywhere)
Step 5: Generate Remediation Plan
Build a prioritized remediation plan:
Phase 1: Quick Wins (days)
- Single-config fixes affecting multiple frameworks
- Expected score improvement per fix
Phase 2: Systematic Fixes (weeks)
- Controls failing across many assets (same root cause)
- Requires policy change or automation
Phase 3: Architectural Changes (months)
- Deep structural gaps requiring design changes
- Network segmentation, encryption-at-rest, etc.
Proactive Remediation Behavior
CRITICAL: Never leave the user with just data. After EVERY output layer, suggest the next action and offer to generate remediation code.
After the dashboard and after every drill-down section:
- Suggest what to do next — identify the highest-ROI fix and recommend it
- Offer remediation format selection — always ask: "I can generate the fix. What format do you prefer?"
- Supported formats: Terraform, CloudFormation, Ansible, CLI commands (aws/az/gcloud), step-by-step instructions, Pulumi, ARM/Bicep
- Auto-suggest quick wins — proactively say "The quickest score improvement is fixing X. Want me to generate the code?"
When the user selects a format:
- Generate the remediation code for the selected control(s) immediately
- Write it to a file:
compliance-fix-<control-id>.<ext> (e.g., .tf, .yml, .sh)
- Include verification commands
- Show projected score improvement after applying
- Suggest the next control to fix
Format mapping:
| User says | Extension | Template |
|---|
| Terraform | .tf | HCL with provider + resource blocks |
| CloudFormation | .cfn.yaml | YAML template with Parameters/Resources |
| Ansible | .yml | Playbook with tasks |
| CLI | .sh | Shell script with cloud CLI commands |
| Instructions | inline | Numbered step-by-step console walkthrough |
| Pulumi | .ts | TypeScript Pulumi program |
| ARM/Bicep | .bicep | Bicep template |
Output Format
Layer 1: Dashboard
═══════════════════════════════════════════════════════════════════
COMPLIANCE GAP ANALYSIS — <framework or "All Frameworks">
<date> | <account scope>
═══════════════════════════════════════════════════════════════════
POSTURE: <overall assessment — 1 line>
┌─────────────────────────────────────────────────────────────────┐
│ FRAMEWORKS <N> enabled │
│ AVG SCORE <X>% │
│ WORST <framework> at <X>% │
│ BEST <framework> at <X>% │
│ TREND (30d) <improving / stable / degrading> │
│ QUICK WINS <N> controls fixable with single changes │
│ WORST ACCOUNT <account> — <X>% avg score │
└─────────────────────────────────────────────────────────────────┘
FRAMEWORK SCORES:
Framework Score Trend Status
─────────────────────────────────────────────────────────
<framework> <X>% ↓ -N% ⚠ DROPPED
<framework> <X>% → 0% ✓ STABLE
<framework> <X>% ↑ +N% ✓ IMPROVING
...
# Show the next line ONLY when fewer than 3 frameworks are enabled.
# Source from get_recommended_compliance_frameworks_to_enable.
Recommended additional frameworks (from connected providers <connected_providers>): <top 3 display_names>
TOP FAILING CONTROLS (highest impact):
[1] <control name> — failing on <N> assets, affects <M> frameworks
[2] <control name> — failing on <N> assets, affects <M> frameworks
[3] <control name> — failing on <N> assets, affects <M> frameworks
RECOMMENDED ACTION:
The fastest score improvement: fix <top control> — affects
<N> assets across <M> frameworks. I can generate the fix now.
What format? terraform | cloudformation | ansible | cli |
instructions | pulumi | arm/bicep
═══════════════════════════════════════════════════════════════════
Or drill down: controls | quick wins | accounts | trends |
remediation plan | <framework name> | full
═══════════════════════════════════════════════════════════════════
Layer 2: Drill-Down Sections
"controls" — All Failing Controls
───────────────────────────────────────────────────────────────────
FAILING CONTROLS — <framework>
Score: <X>% (<P> pass, <F> fail of <T> total)
───────────────────────────────────────────────────────────────────
CRITICAL CONTROLS FAILING:
<control-id> <control name>
Assets failing: <N> | Frameworks: <list>
Fix: <1-line remediation summary>
Failing assets (from get_control_test_assets):
- <name> (<type>) — <ui_url>
- <name> (<type>) — <ui_url>
...
<control-id> <control name>
...
HIGH CONTROLS FAILING:
...
MEDIUM CONTROLS FAILING:
...
(Rendering the real failing assets — name, type, ui_url — per control is what lets
generated remediation code target actual resource IDs instead of a generic template.)
FIX NOW:
Pick any control and I'll generate the remediation code.
Choose format: terraform | cloudformation | ansible | cli |
instructions | pulumi | arm/bicep
───────────────────────────────────────────────────────────────────
"quick wins" — Fastest Path to Improvement
───────────────────────────────────────────────────────────────────
QUICK WINS — Highest ROI Fixes
───────────────────────────────────────────────────────────────────
[1] <control name>
Fix: <specific action>
Impact: passes control in these active frameworks: <active framework
display_names from get_related_compliance_frameworks_for_asset,
filtered to active === true>
Failing assets (from get_control_test_assets):
- <name> (<type>) — <ui_url>
- ...
Score boost: ~<X>% across <frameworks>
Effort: LOW (single config change)
[2] <control name>
...
[3] <control name>
...
ESTIMATED TOTAL IMPROVEMENT:
Fixing all <N> quick wins → +<X>% average score improvement
LET'S DO IT:
I'll generate fixes for all quick wins in one batch.
Choose format: terraform | cloudformation | ansible | cli |
instructions | pulumi | arm/bicep
───────────────────────────────────────────────────────────────────
"accounts" — Account Breakdown
───────────────────────────────────────────────────────────────────
COMPLIANCE BY ACCOUNT
───────────────────────────────────────────────────────────────────
Account Avg Score Worst Framework Failures
──────────────────────────────────────────────────────────────────
<account-1> <X>% <framework> <Y>% <N>
<account-2> <X>% <framework> <Y>% <N>
...
WORST ACCOUNT DEEP DIVE — <account>:
Framework Score Gap from Target
──────────────────────────────────────────
<framework> <X>% -<Y>% from 90%
...
Top failures in this account:
<control> — <N> assets
...
───────────────────────────────────────────────────────────────────
"trends" — Score History
───────────────────────────────────────────────────────────────────
COMPLIANCE TRENDS — Last 30 Days
───────────────────────────────────────────────────────────────────
Date Avg Score Direction Notable Changes
──────────────────────────────────────────────────────
Apr 17 <X>% ─ <note>
Apr 10 <X>% ↓ -N% <note>
Apr 03 <X>% → 0% <note>
Mar 27 <X>% ↑ +N% <note>
FRAMEWORKS THAT DROPPED:
<framework>: <from>% → <to>% (<reason if detectable>)
FRAMEWORKS THAT IMPROVED:
<framework>: <from>% → <to>% (<what was fixed>)
───────────────────────────────────────────────────────────────────
"remediation plan" — Prioritized Fix Plan
───────────────────────────────────────────────────────────────────
REMEDIATION PLAN — Path to <target>% Compliance
───────────────────────────────────────────────────────────────────
PHASE 1: QUICK WINS (this week)
Expected improvement: +<X>%
[ ] <fix 1> — <N> assets, <M> frameworks
[ ] <fix 2> — <N> assets, <M> frameworks
[ ] <fix 3> — ...
PHASE 2: SYSTEMATIC FIXES (this month)
Expected improvement: +<X>%
[ ] <fix pattern> — <N> assets across <M> accounts
[ ] <fix pattern> — ...
PHASE 3: ARCHITECTURAL (this quarter)
Expected improvement: +<X>%
[ ] <change> — requires <team/resource>
[ ] <change> — ...
PROJECTED SCORES AFTER EACH PHASE:
Framework Current Phase 1 Phase 2 Phase 3
─────────────────────────────────────────────────────
<framework> <X>% <Y>% <Z>% <W>%
...
START NOW:
Tell me which phase to start with and your preferred format.
I'll generate implementation code for each fix in that phase.
Format: terraform | cloudformation | ansible | cli |
instructions | pulumi | arm/bicep
───────────────────────────────────────────────────────────────────
"" — Single Framework Deep Dive
Show controls, account breakdown, and remediation plan for just that framework.
"full" — Everything Expanded
Show all sections in order.
Edge Cases
No Compliance Frameworks Enabled
Call get_recommended_compliance_frameworks_to_enable (no params) and render the tenant-aware
recommendations from its response: frameworks[].display_name and connected_providers.
⚠ No compliance frameworks enabled in Orca.
To get started, enable frameworks in:
Orca Console → Compliance → Framework Settings
Recommended for your connected providers (<connected_providers>):
• <frameworks[0].display_name>
• <frameworks[1].display_name>
• <frameworks[2].display_name>
...
If the tool returns an empty frameworks list, fall back to one line: "No tenant-specific recommendations available — enable a CIS Benchmark for your cloud provider to start."
Framework Not Found
⚠ Framework "<input>" not found.
Available frameworks:
<list of enabled frameworks>
Try: /orca-compliance-gap <exact framework name>
Perfect Score
✅ <framework> — 100% compliant!
All <N> controls passing across <M> assets.
Last failure resolved: <date>
Recommendation: Set up alerts for score regression.
MCP Tools Used
Primary Tools
| Tool | Purpose | Parameter |
|---|
get_enabled_compliance_frameworks | All framework scores | optional filters |
get_compliance_trend_over_time | Score history | filters.datetime_filter (7/14/30) |
get_compliance_analysis_by_account_or_business_unit | Account/BU breakdown | group_by ("accounts" or "business_units") |
get_compliance_framework_control_tests | Failing controls per framework | framework_id, optional filters |
get_compliance_framework_stats_for_asset | Per-framework detailed stats | framework_id |
get_framework_assets_with_failed_controls_count | Worst assets per framework | framework_id |
get_control_test_assets | Compliant + non-compliant assets for one control test | framework_id, rule_id |
get_related_compliance_frameworks_for_asset | All frameworks an asset participates in (active + inactive) | asset_unique_id (= group_unique_id from get_control_test_assets) |
get_compliance_analysis_by_account_or_business_unit | Per-account score per framework (heatmap replacement) | group_by: "accounts", framework_ids: ["<id>"] |
Secondary Tools
| Tool | Purpose | When |
|---|
get_control_test_alerts | Alerts for a specific control | "controls" drill-down |
get_recommended_compliance_frameworks_to_enable | Tenant-aware framework recommendations | empty-state edge case + sparse-coverage dashboard hint |
discovery_search | Find assets related to a control failure | When investigating specific gaps |
Parameter Notes
framework_id comes from get_enabled_compliance_frameworks responsefilters object can contain: datetime_filter, providers, accounts, framework_ids, business_unitsdatetime_filter values: 7, 14, 30 (days)group_by is an enum: "accounts" or "business_units"framework_ids on get_compliance_analysis_by_account_or_business_unit is top-level, NOT under filters — nesting it under filters is silently ignored or failsrule_id (e.g. rcad0b53623) is the second key needed for get_control_test_assets, sourced from get_compliance_framework_control_tests → tests[].rule_idasset_unique_id (e.g. CodeRepository_<acct>_<resource> or vm_<acct>_<resource>) for get_related_compliance_frameworks_for_asset is sourced from get_control_test_assets → *_assets[].group_unique_idget_related_compliance_frameworks_for_asset returns inactive frameworks too — filter active: true before counting
Implementation Notes
- Parallelize all initial queries — frameworks, trends, and account breakdown are independent.
- Cross-framework impact is the key ranking metric — a control that fails in 5 frameworks is 5x more impactful to fix.
- Quick wins should have estimated score improvements — calculate from (controls_fixed / total_controls) per framework.
- Account ownership matters — the user needs to know WHO to assign the work to.
- Link to other skills — suggest
/orca-alert-triage for individual alert deep-dives from failing controls, /orca-impact-analysis for fix impact.
- Compliance tools are the most complete in the Orca MCP — leverage all of them.
- Avoid the redundant account round-trip —
get_enabled_compliance_frameworks already returns top_accounts and stats.accounts.data (per-account pass/fail counts across the framework). Only call get_compliance_analysis_by_account_or_business_unit when you need the per-account score per framework (e.g. the heatmap replacement in Query 9); otherwise prefer the inline data.
Response sizes are large — always scope first
Every compliance tool can return tens to hundreds of KB. Without scoping, the skill will hit context limits before it can rank or render. Default scoping rules:
get_compliance_framework_control_tests: pass filters.providers and/or filters.assets_categories whenever the user query implies a scope (e.g. "PCI on AWS" → providers: ["aws"]).get_control_test_assets: call only on the top-N failing controls (default N=5), never on every failing control by default.get_related_compliance_frameworks_for_asset: call only on the top-N failing assets per control (default N=3), and de-duplicate by group_unique_id across controls.get_enabled_compliance_frameworks: when answering a single-framework question, pass filters.framework_ids: ["<id>"] instead of fetching all.
