# DESA Platform Architecture

## System Overview

DESA (Dynamic Encoded Script Analysis) is a multi-tenant security analysis platform for detecting and deobfuscating malicious PowerShell scripts. The platform integrates with the PlatphormNews network for enhanced threat intelligence and collaborative analysis.

## Architecture Diagram

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                              DESA PLATFORM                                   │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
│  │   Next.js   │  │   API v1    │  │  Webhooks   │  │    Jobs     │         │
│  │  Frontend   │  │   Routes    │  │   Engine    │  │   Queue     │         │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘         │
│         │                │                │                │                 │
│         └────────────────┴────────────────┴────────────────┘                 │
│                                    │                                         │
│                      ┌─────────────┴─────────────┐                          │
│                      │     Analysis Engine       │                          │
│                      │  ┌──────┐ ┌──────┐ ┌────┐ │                          │
│                      │  │Decode│ │Detect│ │IOC │ │                          │
│                      │  └──────┘ └──────┘ └────┘ │                          │
│                      └─────────────┬─────────────┘                          │
│                                    │                                         │
│                      ┌─────────────┴─────────────┐                          │
│                      │     Neon PostgreSQL       │                          │
│                      │  ┌──────────────────────┐ │                          │
│                      │  │ Scripts | Rules | IOC│ │                          │
│                      │  └──────────────────────┘ │                          │
│                      └───────────────────────────┘                          │
│                                                                              │
└─────────────────────────────────────────────────────────────────────────────┘
                                    │
                                    │ PlatphormNews Network
                                    ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                         PLATPHORMNEWS NETWORK                                │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
│  │ msi.plat... │  │ svg.plat... │  │kanban.plat..│  │ mcp.plat... │         │
│  │  MSI Data   │  │  SVG Gen    │  │   Boards    │  │    MCP      │         │
│  └─────────────┘  └─────────────┘  └─────────────┘  └─────────────┘         │
│                                                                              │
│  ┌─────────────┐  ┌─────────────┐                                           │
│  │ xml.plat... │  │ json.plat.. │                                           │
│  │  XML Feeds  │  │  JSON APIs  │                                           │
│  └─────────────┘  └─────────────┘                                           │
│                                                                              │
└─────────────────────────────────────────────────────────────────────────────┘
```

## Core Components

### 1. Frontend Layer (Next.js 16 App Router)

- **Technology**: Next.js 16, React 19, TypeScript, Tailwind CSS v4
- **Features**:
  - Server Components for optimal performance
  - Monaco Editor for script editing
  - Real-time analysis feedback
  - Responsive design (mobile, tablet, desktop)

### 2. API Layer

- **Base URL**: `/api/v1`
- **Authentication**: JWT tokens, API keys
- **Rate Limiting**: Per-tenant, configurable limits
- **Documentation**: OpenAPI 3.0 spec

### 3. Analysis Engine

- **Deobfuscation**: Multi-layer recursive decoding (Base64, GZIP, XOR, URL encoding, hex, char arrays)
- **XOR Key Extraction**: Detects XOR encryption, brute-forces single/multi-byte keys, and recovers plaintext
- **C2 Config Extraction**: Parses C2 URLs, beacon intervals, callback hosts, and HTTP profiles from script context  
- **Payload URL Detection**: Extracts download cradle targets (Invoke-WebRequest, WebClient, Start-BitsTransfer)
- **IOC Extraction**: IPs, domains, URLs, file hashes (MD5/SHA1/SHA256), registry keys, file paths, email addresses
- **Threat Detection**: 20+ built-in pattern matchers + custom DB rules with MITRE ATT&CK mapping
- **Threat Scoring**: 0–100 weighted score based on severity distribution (critical: 35pts, high: 20pts, etc.)
- **VirusTotal Integration**: Optional enrichment for file hashes and network IOCs via VT API v3
- **Entropy Analysis**: Shannon entropy scanning to flag suspicious high-entropy encoded regions

### 4. Database Layer (Neon PostgreSQL)

- **Multi-tenancy**: Tenant isolation via `tenant_id`
- **Soft deletes**: `deleted_at` timestamp
- **Audit logging**: Comprehensive change tracking
- **Metadata**: JSONB columns for extensibility

## PlatphormNews Integration Architecture

### Integration Services

| Service | URL | Purpose | Protocol |
|---------|-----|---------|----------|
| MSI | https://msi.platphormnews.com | Malware Sample Intelligence | REST/GraphQL |
| SVG | https://svg.platphormnews.com | Visual Report Generation | REST |
| Kanban | https://kanban.platphormnews.com | Workflow Management | REST/WebSocket |
| MCP | https://mcp.platphormnews.com | Model Context Protocol | MCP |
| XML | https://xml.platphormnews.com | Legacy Feed Integration | XML/RSS |
| JSON | https://json.platphormnews.com | Modern API Gateway | REST/JSON |

### Data Flow

```
Script Upload → DESA Analysis → Event Generated
                                      │
         ┌────────────────────────────┼────────────────────────────┐
         ▼                            ▼                            ▼
   JSON Export                  Kanban Card                  SVG Report
   (json.plat...)              (kanban.plat...)             (svg.plat...)
         │                            │                            │
         ▼                            ▼                            ▼
   MSI Enrichment              MCP Intelligence              XML Feed
   (msi.plat...)               (mcp.plat...)               (xml.plat...)
```

## Security Architecture

### Authentication

1. **Session-based**: For web UI users
2. **API Keys**: For programmatic access
3. **JWT Tokens**: For service-to-service communication

### Authorization

- Role-based access control (RBAC)
- Tenant isolation
- Resource-level permissions

### Data Protection

- Password hashing: bcrypt
- Secrets: Environment variables
- TLS: Required for all connections
- Input validation: Zod schemas

## Scalability Considerations

### Horizontal Scaling

- Stateless API design
- Database connection pooling (Neon serverless)
- Queue-based job processing

### Caching Strategy

- `use cache` directive for static content
- SWR for client-side data fetching
- CDN for static assets

### Performance Targets

| Metric | Target |
|--------|--------|
| API Response Time | < 200ms (p95) |
| Analysis Time | < 5s (typical script) |
| Concurrent Users | 1000+ |
| Uptime | 99.9% |

## Monitoring & Observability

### Metrics

- Vercel Analytics for frontend
- Custom metrics for analysis engine
- Database query performance

### Logging

- Structured JSON logs
- Request ID correlation
- Tenant/user context

### Alerting

- Error rate thresholds
- Latency anomalies
- Integration health checks

## Deployment Architecture

```
┌─────────────────────────────────────────────────────────────────┐
│                         Vercel Edge                             │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐        │
│  │ Preview  │  │Production│  │   Edge   │  │Middleware│        │
│  │   Env    │  │   Env    │  │Functions │  │          │        │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘        │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                      Neon PostgreSQL                            │
│           (Serverless, Auto-scaling, Branching)                 │
└─────────────────────────────────────────────────────────────────┘
```

## Version Information

- **Platform Version**: 0.0.1
- **API Version**: v1
- **Schema Version**: 001
- **Last Updated**: 2026-03-03