orca-compliance-gap

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:

1. 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.
2. Asset count — controls failing on many assets = systematic issue
3. Severity — critical/high controls before medium/low
4. 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:

1. Suggest what to do next — identify the highest-ROI fix and recommend it
2. Offer remediation format selection — always ask: "I can generate the fix. What format do you prefer?"
3. Supported formats: Terraform, CloudFormation, Ansible, CLI commands (aws/az/gcloud), step-by-step instructions, Pulumi, ARM/Bicep
4. 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 response
• filters object can contain: datetime_filter, providers, accounts, framework_ids, business_units
• datetime_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 fails
• rule_id (e.g. rcad0b53623) is the second key needed for get_control_test_assets, sourced from get_compliance_framework_control_tests → tests[].rule_id
• asset_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_id
• get_related_compliance_frameworks_for_asset returns inactive frameworks too — filter active: true before counting

Implementation Notes

1. Parallelize all initial queries — frameworks, trends, and account breakdown are independent.
2. Cross-framework impact is the key ranking metric — a control that fails in 5 frameworks is 5x more impactful to fix.
3. Quick wins should have estimated score improvements — calculate from (controls_fixed / total_controls) per framework.
4. Account ownership matters — the user needs to know WHO to assign the work to.
5. Link to other skills — suggest /orca-alert-triage for individual alert deep-dives from failing controls, /orca-impact-analysis for fix impact.
6. Compliance tools are the most complete in the Orca MCP — leverage all of them.
7. 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.