Reports - SoCMate

SoCMate generates branded PDF security reports by pulling live data from Microsoft Sentinel and Heimdal Security. Reports can be one-time or scheduled for recurring delivery.

Report Styles

Document

Traditional paginated report with executive summary, narrative analysis, charts, and tables. Best for investigation summaries and compliance.

Presentation

Branded slide-deck PDF matching your PowerPoint template. Cover slide, gradient headers, company logos, one section per page. Best for daily SOC reports and stakeholder briefings.

Creating a Report

From the UI

Navigate to Reports > New Report (/reports/new)
Enter a title and select Document or Presentation (Slide Deck)
Configure the schedule (daily, weekly, monthly, or one-time)
Add report sections in Step 2 — each section can pull data from:
- LLM — AI-generated narrative analysis
- Sentinel KQL — live query against Microsoft Sentinel
- Heimdal API — endpoint protection data from Heimdal Security
Validate and create

Using a Seed Template

For the standard Daily Internal SOC Report (matching the Paramount/NXXT/Ahlan Cyber branded template), use the seed endpoint to create a pre-configured template with all 8 slides:

Seed the template

curl -X POST https://agent.socmate.yourcompany.com/api/v1/reports/templates/seed-daily-soc \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json"

This creates a presentation-mode template with:

Slide	Data Source	Content
Security Posture & Incident Classification	Sentinel KQL	Grouped bar chart by severity
Security Alerts by Product	Sentinel KQL	Bar chart by product
Top 10 Incidents	Sentinel KQL	Table with severity
Dark Layer Endpoint Status	Heimdal API	Traffic & attack type charts
NGAV Status	Heimdal API	Donut charts
Extended Threat Protection	Heimdal API	Severity bar + category donut
Ransomware Encryption	Heimdal API	Detection by OS charts
Device Status	Heimdal API	Device count & status donuts

Create a schedule

curl -X POST https://agent.socmate.yourcompany.com/api/v1/reports/schedules \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Daily Internal SOC Report",
    "template_id": "<template_id from step 1>",
    "user_query": "Daily SOC report",
    "persona": "soc_analyst",
    "frequency": "daily",
    "scheduled_time": "08:00",
    "timezone": "Asia/Dubai",
    "recipients": [
      {
        "user_id": "user_id",
        "email": "soc-team@company.com",
        "delivery": "email"
      }
    ],
    "run_immediately": true
  }'

View the report

Go to Reports in the sidebar. The generated report appears in the list. Click to view the web version, or download the branded PDF.

From Inside the Cluster

If you need to seed without a JWT (e.g., during initial setup), run directly from the agent pod:

kubectl exec -n socmate <agent-pod> -- python3 -c "
import asyncio
from motor.motor_asyncio import AsyncIOMotorClient
from beanie import init_beanie
from shared_infra.models.report_template import ReportTemplateDocument
import os

async def seed():
    client = AsyncIOMotorClient(os.environ['MONGODB_URL'])
    await init_beanie(database=client[os.environ['MONGODB_DB_NAME']], document_models=[ReportTemplateDocument])
    from src.core.seed.daily_soc_report_template import seed_daily_soc_template
    doc = await seed_daily_soc_template()
    print(f'Seeded: {doc.template_id}')

asyncio.run(seed())
"

Data Sources

Sentinel KQL

Sections with data_source: sentinel_kql execute a KQL query against Microsoft Sentinel and format the results as charts or tables. The query is defined in data_config.kql:

{
  "data_source": "sentinel_kql",
  "data_config": {
    "kql": "SecurityIncident | summarize count() by Severity",
    "time_range": "PT24H",
    "chart": {
      "type": "grouped_bar",
      "xKey": "Severity",
      "categories": ["TotalCases", "Resolved", "Active"]
    }
  }
}

Heimdal API

Sections with data_source: heimdal_api fetch from Heimdal Security endpoints. The adapter aggregates raw records into chart-ready data. Configure with data_config.endpoint:

{
  "data_source": "heimdal_api",
  "data_config": {
    "endpoint": "dark_layer",
    "chart_keys": ["total_count", "prevented_attack_types"]
  }
}

Available endpoints: dark_layer, ngav, xtp, ransomware, devices.

LLM

Sections with data_source: llm (default) use AI to generate narrative content, chart data, or table data based on the user query. This is the original report mode.

Configuration

Environment Variables

For Sentinel data (already configured if SIEM provider is set up):

SENTINEL_WORKSPACE_ID, SENTINEL_TENANT_ID, SENTINEL_CLIENT_ID, SENTINEL_CLIENT_SECRET

For Heimdal data:

HEIMDAL_API_URL — Heimdal API base URL
HEIMDAL_API_KEY — API key for authentication
HEIMDAL_CUSTOMER_ID — Your Heimdal customer ID

Customizing the Theme

The presentation template supports custom branding via the theme field on the template:

{
  "render_mode": "presentation",
  "theme": {
    "bg_color": "#09392F",
    "accent_color": "#1EBE9B",
    "gradient_start": "#26AD87",
    "gradient_mid": "#E7FF2A",
    "gradient_end": "#1F70AD"
  }
}

Custom logos can be provided via logo_data_uri in the theme (base64-encoded PNG). The default uses the embedded Paramount/NXXT/Ahlan Cyber logo strip.

Chart Types

Presentation reports support these chart types for data-driven sections:

Type	Use Case	Renderer
`bar`	Single-series bar chart	matplotlib
`grouped_bar`	Multi-series comparison with data table	matplotlib
`donut`	Proportional breakdown with center total	matplotlib
`line`	Trends over time	matplotlib
`pie`	Simple proportional breakdown	matplotlib
`area`	Filled time series	matplotlib

Side-by-side layouts are supported — set chart_keys with two keys in data_config to render two charts horizontally on one slide.

​Report Styles

Document

Presentation

​Creating a Report

​From the UI

​Using a Seed Template

​From Inside the Cluster

​Data Sources

​Sentinel KQL

​Heimdal API

​LLM

​Configuration

​Environment Variables

​Customizing the Theme

​Chart Types