Use Case 021: Capability Declaration Inventory (formerly: Compliance Security Assessment)

⚠️ Important — this use case has been renamed and rescoped. The original title implied a security audit. The implemented feature is a capability declaration inventory: it compares the SDK security capabilities each application self-declares at registration against framework templates (SOC 2, HIPAA, FedRAMP, StateRAMP). It does not perform active probing, configuration inspection, or external evidence collection. Scores reflect coverage of self-attested declarations, not audited posture. An evidence-based audit platform is on the roadmap; this document describes the inventory feature as implemented today, with terminology corrected.

Overview

Description

This use case describes how Application Manager enables Security Administrators to evaluate the SDK security capabilities each registered application self-declared at startup against industry-standard framework templates (SOC 2, HIPAA, FedRAMP, StateRAMP) and custom templates. Administrators can trigger on-demand re-evaluation, view per-application declaration reports with control-level detail, monitor coverage trends over time, and review the platform-wide inventory dashboard showing an application × framework matrix. The system also supports scheduled automated re-evaluation and extensible compliance templates authored by administrators through the Configuration Manager.

What the feature does not do. It does not actively probe applications, inspect their running configuration, sample audit logs, query cloud control planes, or otherwise collect evidence independent of what each application's SDK declares. A score of 100 means the application claimed every capability the framework template asks for; it does not mean the underlying implementations work or that the application would pass an external audit.

Actors

Preconditions

1. Application Manager is running and accessible
2. User authenticated with SecurityAdmin policy authorization
3. At least one application registered in the system
4. Riptide Platform Security SDK is configured with compliance assessment capabilities
5. StateRAMP built-in template is loaded (always available)
6. Optional: Custom compliance templates authored at /security/compliance-templates.json

Postconditions

Success Postconditions

1. Assessment record persisted with score (0–100) and full report JSON
2. Control-level pass/fail results available for review
3. Dashboard updated with latest scores in application × framework matrix
4. Trend data available for historical score tracking
5. Audit event logged with triggering user and framework details

Failure Postconditions

1. Assessment failure logged with error details
2. User notified via TempData error message
3. Previous assessment data remains unchanged
4. No partial assessment records written

Triggers

• Security Administrator navigates to Platform Security Dashboard
• Security Administrator triggers a manual compliance audit for an application
• Scheduled audit background service fires (configurable interval, default: 24 hours)
• Administrator publishes updated custom compliance templates via Configuration Manager
• New application registered and initial compliance baseline needed

Basic Flow (Happy Path — Manual Compliance Audit)

Alternative Flows

Alt-1: Scheduled Automated Audit

Trigger: SecurityAuditBackgroundService timer fires (configurable interval)

Flow:

1. Background service wakes at configured interval (default: 24 hours)
2. Service loads configured frameworks from SecurityAudit:ScheduledAudit:Frameworks
3. Service retrieves all active registered applications
4. For each application × framework combination:
   1. Loads templates via ComplianceTemplateLoader
   2. Runs assessment via IComplianceAssessor
   3. Persists result with Source = AuditSource.Scheduled, TriggeredBy = "scheduler"
5. Service logs completion summary
6. Next run scheduled based on IntervalHours configuration

Alt-2: No Assessments Exist for Application

Trigger: Security Administrator views report for application with no prior assessments

Flow:

1. Admin navigates to /security/report/{applicationId}
2. Controller queries assessments — returns empty
3. Controller returns NoAssessments.cshtml view
4. View displays empty state with framework selector dropdown
5. Admin selects a framework and clicks "Run First Audit"
6. System runs audit (continues with Basic Flow step: POST audit)

Alt-3: Custom Compliance Template Authoring

Trigger: Administrator adds/modifies custom compliance templates

Flow:

1. Admin navigates to Configuration Manager
2. Admin creates/edits /security/compliance-templates.json under the application-manager managed application
3. JSON contains array of CompliancePolicyTemplate objects with controls
4. On next audit run, ComplianceTemplateLoader:
   1. Loads JSON file from Configuration DB
   2. Deserializes template definitions
   3. Validates SDK capability references (logs warnings for unknown capabilities)
   4. Registers templates in ComplianceTemplateRegistry
5. Custom templates appear as framework options for audits

Alt-4: Assessment Failure

Trigger: Compliance assessment throws an exception

Flow:

1. Admin triggers manual audit
2. ComplianceAssessor.AssessAsync() throws exception
3. Controller catches exception, logs error with application ID and framework
4. TempData["Error"] set with failure message
5. Admin redirected to report page with error notification
6. No assessment record written — previous data unchanged

Alt-5: Framework Switching on Report

Trigger: Admin views report and switches to different framework

Flow:

1. Admin viewing report for application with multiple framework assessments
2. Available frameworks shown in framework switcher
3. Admin selects different framework from dropdown
4. Page reloads with ?framework={selected} query parameter
5. Report displays controls, score, and trend for selected framework

Business Rules

Authorization Rules

• BR-021-01: All compliance features require SecurityAdmin policy authorization
• BR-021-02: Only SecurityAdmin users can trigger manual audits
• BR-021-03: Scheduled audits run with system-level permissions

Scoring Rules

• BR-021-04: Compliance scores range from 0 to 100
• BR-021-05: Scores are color-coded: green ≥ 80, yellow 50–79, red < 50
• BR-021-06: Severity-weighted scoring: Critical (4×), High (3×), Medium (2×), Low (1×)
• BR-021-07: Unassessed applications display neutral/grey indicator

Template Rules

• BR-021-08: StateRAMP built-in template is always registered and cannot be overridden by custom templates
• BR-021-09: Custom templates loaded from /security/compliance-templates.json in Configuration Manager
• BR-021-10: Templates refreshed on every audit run (no restart required for template changes)
• BR-021-11: Unknown SDK capability references are logged as warnings but controls are still evaluated

Assessment Persistence Rules

• BR-021-12: Each assessment is a point-in-time record — never updated, only new records added
• BR-021-13: Full ComplianceReport stored as JSON for control-level drill-down
• BR-021-14: AuditSource tracks whether assessment was Manual, Scheduled, or OnDemand
• BR-021-15: TriggeredBy records username for manual audits, "scheduler" for automated

Scheduled Audit Rules

• BR-021-16: Scheduled audits disabled by default (SecurityAudit:ScheduledAudit:Enabled: false)
• BR-021-17: Default interval is 24 hours (IntervalHours: 24)
• BR-021-18: Configured frameworks: SOC2, HIPAA, FedRAMP, StateRAMP

Data Model

ApplicationSecurityAssessment Entity

Supporting Enums

• ComplianceFramework: SOC2, HIPAA, FedRAMP, StateRAMP, Custom
• AuditSource: Manual, Scheduled, OnDemand

API Endpoints

View Components

Dashboard (Dashboard.cshtml)

• Application × framework matrix table
• Color-coded score badges (green/yellow/red/grey)
• Links to per-application detail reports
• Last assessed timestamps

Report (Report.cshtml)

• Headline score display with framework name
• Control results table: ID, name, category, severity, pass/fail status, gap description, remediation
• Historical trend chart (line graph of scores over time)
• Framework switcher for multi-framework applications
• "Run Audit" button to trigger new assessment

No Assessments (NoAssessments.cshtml)

• Empty state UI for first-time assessment
• Framework dropdown selector
• "Run First Audit" action button

Test Scenarios

Dependencies

• Riptide Platform Security SDK (IComplianceAssessor, ComplianceTemplateRegistry)
• Riptide Platform Logging SDK (IRiptideLogger)
• Configuration Manager (for custom template storage)
• IdentityDbContext (for assessment persistence)