Version: 2026.04 | Last Updated: April 2026| Status: Draft

Reports

Generate AI-powered executive briefs and compliance reports with automated scheduling and distribution.

Overview

The Executive Brief system provides automated security summaries, threat analysis, and actionable recommendations for stakeholders.

Source: ow-ai-backend/routes/executive_brief_routes.py (SEC-065)

Compliance: SOC 2 AU-6, SOC 2 AU-7, NIST AU-6, PCI-DSS 10.6

warning

Executive briefs contain sensitive security metrics and threat data. Verify recipient distribution lists before scheduling automated report delivery to avoid data exposure.

Executive Briefs

Brief Contents

Each executive brief includes:

Section	Description
Summary	High-level threat overview
Key Metrics	Threats detected, prevented, cost savings
Recommendations	Prioritized action items
Risk Assessment	Overall security posture
Distribution List	Recipients

Brief Response Structure

{
  "brief_id": "brief_20260402_a1b2c3",
  "generated_at": "2026-04-02T10:00:00Z",
  "generated_by": "admin@company.com",
  "expires_at": "2026-04-03T10:00:00Z",
  "time_period": "24h",
  "alert_count": 47,
  "high_priority_count": 12,
  "critical_count": 3,
  "summary": "Security posture remains strong with 47 alerts processed...",
  "key_metrics": {
    "threats_detected": 47,
    "threats_prevented": 44,
    "cost_savings": "$150,000",
    "system_accuracy": "93.6%"
  },
  "recommendations": [
    {
      "priority": "high",
      "action": "Review elevated database access patterns",
      "timeframe": "24 hours",
      "owner": "Security Team"
    }
  ],
  "risk_assessment": "MEDIUM",
  "generation_method": "ai_generated",
  "is_current": true,
  "version": 1
}

Getting Latest Brief

Retrieve the current cached executive brief:

curl https://pilot.owkai.app/api/executive-briefs/latest \
  -H "Authorization: Bearer owkai_your_api_key"

Performance: <100ms (indexed query)

Behavior

Returns cached brief if valid
If no cached brief exists, generates new one
Records view in audit trail

Regenerating Briefs

Force regeneration with fresh data:

curl -X POST https://pilot.owkai.app/api/executive-briefs/regenerate \
  -H "Authorization: Bearer owkai_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "time_period": "24h",
    "force": false
  }'

Time Periods

Period	Description
`24h`	Last 24 hours
`7d`	Last 7 days
`30d`	Last 30 days
`90d`	Last 90 days

Rate Limiting

Cooldown: 5 minutes between regenerations
Force: Admin-only bypass for cooldown

Checking Cooldown

Before regenerating, check if allowed:

curl https://pilot.owkai.app/api/executive-briefs/cooldown \
  -H "Authorization: Bearer owkai_your_api_key"

Response:

{
  "can_regenerate": true,
  "seconds_remaining": 0,
  "message": "Regeneration available"
}

Or if rate limited:

{
  "can_regenerate": false,
  "seconds_remaining": 180,
  "message": "Please wait 180 seconds before regenerating"
}

Brief History

Retrieve historical briefs for audit purposes:

curl "https://pilot.owkai.app/api/executive-briefs/history?limit=10&offset=0" \
  -H "Authorization: Bearer owkai_your_api_key"

Response:

{
  "briefs": [
    {
      "brief_id": "brief_20260402_a1b2c3",
      "generated_at": "2026-04-02T10:00:00Z",
      "time_period": "24h",
      "alert_count": 47,
      "is_current": true
    },
    {
      "brief_id": "brief_20260401_d4e5f6",
      "generated_at": "2026-04-01T10:00:00Z",
      "time_period": "24h",
      "alert_count": 52,
      "is_current": false
    }
  ],
  "total": 2,
  "limit": 10,
  "offset": 0
}

Getting Specific Brief

Retrieve a brief by ID:

curl https://pilot.owkai.app/api/executive-briefs/{brief_id} \
  -H "Authorization: Bearer owkai_your_api_key"

Use for:

Viewing historical briefs
Sharing specific briefings
Audit record access

Key Metrics (SEC-066)

All briefs use the Unified Metrics Engine for consistent calculations:

Threat Metrics

Metric	Description	Calculation
`threats_detected`	Total alerts in period	COUNT(alerts)
`threats_prevented`	Acknowledged alerts	COUNT(acknowledged)
`threats_pending`	Unacknowledged alerts	COUNT(pending)

Financial Metrics

Metric	Description	Formula
`cost_savings`	Estimated savings	threats_prevented × $50,000

Performance Metrics

Metric	Description	Formula
`accuracy_rate`	Resolution rate	(acknowledged / total) × 100
`false_positive_rate`	Dismissed alerts	(dismissed / total) × 100

Recommendations

Briefs include prioritized recommendations:

Recommendation Structure

{
  "priority": "high",
  "action": "Review elevated database access patterns",
  "timeframe": "24 hours",
  "owner": "Security Team"
}

Priority Levels

Priority	Response Time	Description
Critical	Immediate	Active threat requiring response
High	< 24 hours	Elevated risk needing attention
Medium	< 7 days	Should be addressed soon
Low	As scheduled	Monitor and review

Risk Assessment

Overall security posture evaluation:

Level	Score Range	Description
Critical	80-100	Immediate action required
High	60-79	Elevated risk
Medium	40-59	Moderate risk
Low	0-39	Acceptable risk

Brief Metadata

Each brief includes metadata for audit:

Field	Description
`organization_id`	Multi-tenant isolation
`has_activity`	Whether org has alerts
`llm_model`	AI model used
`generation_time_ms`	Generation duration

API Reference

Endpoint	Method	Description
`/api/executive-briefs/latest`	GET	Get latest brief
`/api/executive-briefs/regenerate`	POST	Regenerate brief
`/api/executive-briefs/cooldown`	GET	Check cooldown
`/api/executive-briefs/history`	GET	Get brief history
`/api/executive-briefs/{id}`	GET	Get specific brief
`/api/executive-briefs/generate`	POST	Legacy endpoint

Source: ow-ai-backend/routes/executive_brief_routes.py

Scheduled Reports

Creating a Report Schedule

curl -X POST https://pilot.owkai.app/api/users/reports/scheduled \
  -H "Authorization: Bearer owkai_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Weekly Executive Summary",
    "report_type": "executive_dashboard",
    "schedule": "0 9 * * 1",
    "format": "pdf",
    "recipients": ["exec@company.com"],
    "enabled": true
  }'

Report Types

Type	Description
`executive_dashboard`	High-level KPIs and trends
`risk_analysis`	Detailed risk breakdown
`compliance_summary`	Compliance scores and gaps
`agent_performance`	Per-agent metrics
`audit_summary`	Audit log summary

Schedule Format (Cron)

9 * * 1  = Every Monday at 9 AM
9 * * *  = Every day at 9 AM
9 1 * *  = First of month at 9 AM

Best Practices

Generate daily briefs: Keep stakeholders informed
Review recommendations: Prioritize by urgency
Track history: Maintain audit compliance
Distribute appropriately: Use distribution list feature
Monitor cost savings: Demonstrate ROI

Troubleshooting

Brief generation failing

Solution: Check organization has alert data; empty state returns minimal brief.

Rate limit errors (429)

Solution: Wait for cooldown period; check /cooldown endpoint.

Metrics showing zero

Solution: Verify alerts exist in time period; check organization_id filtering.

Brief not updating

Solution: Use /regenerate endpoint to force refresh.

Source: executive_brief_routes.py, executive_brief_service.py

Overview​

Executive Briefs​

Brief Contents​

Brief Response Structure​

Getting Latest Brief​

Behavior​

Regenerating Briefs​

Time Periods​

Rate Limiting​

Checking Cooldown​

Brief History​

Getting Specific Brief​

Key Metrics (SEC-066)​

Threat Metrics​

Financial Metrics​

Performance Metrics​

Recommendations​

Recommendation Structure​

Priority Levels​

Risk Assessment​

Brief Metadata​

API Reference​

Scheduled Reports​

Creating a Report Schedule​

Report Types​

Schedule Format (Cron)​

Best Practices​

Troubleshooting​

Brief generation failing​

Rate limit errors (429)​

Metrics showing zero​

Brief not updating​