# DESA — Data Documentation

> **Version:** 1.0.0
> **Maintained by:** [Platphorm News](https://platphormnews.com)
> **Last Updated:** 2025-03-07

## Overview

This document describes the data models, schemas, and data flows used by DESA (Dynamic Encoded Script Analysis).

## Data Models

### Script

Represents a submitted PowerShell script for analysis.

| Field | Type | Description |
|-------|------|-------------|
| `id` | string | Unique identifier (UUID) |
| `name` | string | Script filename or label |
| `content` | text | Raw script content |
| `hash` | string | SHA-256 hash of content |
| `size` | integer | Content size in bytes |
| `created_at` | timestamp | Submission timestamp |
| `updated_at` | timestamp | Last modification |

### Analysis Result

Output from the 7-stage analysis pipeline.

| Field | Type | Description |
|-------|------|-------------|
| `id` | string | Unique identifier |
| `script_id` | string | Foreign key to Script |
| `threat_score` | float | Overall threat score (0.0–10.0) |
| `risk_level` | enum | `critical`, `high`, `medium`, `low`, `info` |
| `findings` | array | Detection rule matches |
| `iocs` | array | Extracted IOCs |
| `deobfuscated_content` | text | Deobfuscated script content |
| `mitre_mappings` | array | MITRE ATT&CK technique IDs |
| `pipeline_metadata` | object | Processing timestamps per stage |

### Finding

A detection rule match within an analysis.

| Field | Type | Description |
|-------|------|-------------|
| `rule_id` | string | Detection rule identifier |
| `rule_name` | string | Human-readable rule name |
| `severity` | enum | `critical`, `high`, `medium`, `low`, `info` |
| `confidence` | float | Match confidence (0.0–1.0) |
| `description` | string | Finding description |
| `line_number` | integer | Source line number |
| `matched_content` | string | Matched code snippet |
| `mitre_technique` | string | MITRE ATT&CK technique ID |

### IOC (Indicator of Compromise)

Extracted indicators from analyzed scripts.

| Field | Type | Description |
|-------|------|-------------|
| `id` | string | Unique identifier |
| `type` | enum | `ipv4`, `ipv6`, `domain`, `url`, `md5`, `sha1`, `sha256`, `email`, `filepath`, `registry`, `ja4` |
| `value` | string | IOC value |
| `confidence` | float | Extraction confidence (0.0–1.0) |
| `context` | string | Surrounding code context |
| `line_number` | integer | Source line number |
| `threat_intel` | object | Enrichment data from MSI |

### Detection Rule

Pattern matching rules used by the analysis engine.

| Field | Type | Description |
|-------|------|-------------|
| `id` | string | Rule identifier |
| `name` | string | Rule name |
| `description` | string | What the rule detects |
| `category` | enum | `obfuscation`, `execution`, `persistence`, `evasion`, `collection`, `exfiltration`, `credential_access`, `discovery`, `lateral_movement` |
| `severity` | enum | `critical`, `high`, `medium`, `low`, `info` |
| `pattern` | string | Detection pattern (regex) |
| `mitre_technique` | string | MITRE ATT&CK mapping |
| `enabled` | boolean | Rule active state |

## Data Flows

### Analysis Pipeline

```
Input Script
     │
     ▼
┌──────────┐   ┌──────────┐   ┌───────────┐   ┌──────────┐
│  Ingest  │──▶│  Decode  │──▶│ Normalize │──▶│  Detect  │
└──────────┘   └──────────┘   └───────────┘   └──────────┘
                                                     │
                                                     ▼
                                               ┌──────────┐   ┌───────────┐   ┌───────────┐
                                               │  Enrich  │──▶│   Score   │──▶│ Summarize │
                                               └──────────┘   └───────────┘   └───────────┘
                                                                                     │
                                                                                     ▼
                                                                              Analysis Result
```

### Integration Data Flow

```
DESA Analysis Result
     │
     ├──▶ MSI: Malware sample enrichment
     ├──▶ JSON: Structured export (STIX, MISP, OpenCTI)
     ├──▶ SVG: Visual report generation
     ├──▶ XML: RSS/Atom feed publication
     └──▶ MCP Hub: Tool capability registration
```

## API Response Formats

### Standard Success Response

```json
{
  "success": true,
  "data": { ... },
  "meta": {
    "requestId": "req_abc123",
    "timestamp": "2025-03-07T00:00:00.000Z",
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 100,
      "totalPages": 5
    }
  }
}
```

### Standard Error Response

```json
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid script content",
    "details": { ... }
  }
}
```

## Encoding Support

DESA detects and decodes the following encoding types:

| Encoding | Detection Method | Recursive |
|----------|-----------------|-----------|
| Base64 | Pattern matching + entropy analysis | Yes |
| Hexadecimal | 0x prefix or continuous hex string | Yes |
| XOR | Known key patterns and frequency analysis | Yes |
| GZIP | Magic bytes (1f 8b) | Yes |
| Deflate | Zlib header detection | Yes |
| Unicode | BOM and encoding markers | Yes |
| Concatenation | String join/concat patterns | Yes |

## Links

- **API Specification:** [docs/API.md](./API.md)
- **Architecture:** [docs/ARCHITECTURE.md](./ARCHITECTURE.md)
- **PlatphormNews:** [platphormnews.com](https://platphormnews.com)