# wormless-framework/wormless-api architecture

> Architecture diagram of the GitHub repository wormless-framework/wormless-api, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/wormless-framework/wormless-api
- Repository: https://github.com/wormless-framework/wormless-api

## Overview

Wormless API is a Spring backend for malware and vulnerability analysis, threat intelligence, and SOC workflows. Its principal flow accepts an uploaded file, validates and persists file/job records, sends the file to an external sandbox, stores the raw result, and exposes job status/results. The tree also shows distinct dependency scanning, threat indicators, vulnerability management, detection/blocking policy, remediation, reporting, CI/CD pipeline, and user capabilities. Detailed wiring is shown only where sampled source supports it; other feature branches are represented without speculative call edges.

Main entry points: [`src/main/java/com/wormless/services/SandboxService.java`](https://github.com/wormless-framework/wormless-api/blob/main/src/main/java/com/wormless/services/SandboxService.java) (Analysis orchestration), [`src/main/java/com/wormless/controller/SandboxController.java`](https://github.com/wormless-framework/wormless-api/blob/main/src/main/java/com/wormless/controller/SandboxController.java) (Sandbox endpoints), [`src/main/java/com/wormless/services/ArquivoService.java`](https://github.com/wormless-framework/wormless-api/blob/main/src/main/java/com/wormless/services/ArquivoService.java) (File validation), [`src/main/java/com/wormless/repository/ArquivoRepository.java`](https://github.com/wormless-framework/wormless-api/blob/main/src/main/java/com/wormless/repository/ArquivoRepository.java) (File repository)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_analysis["File Analysis"]
  node_sandbox_controller["Sandbox endpoints"]
  node_sandbox_service["Analysis orchestration"]
  node_file_service["File validation"]
  node_file_repo["File repository"]
  node_job_service["Job lifecycle"]
  node_job_repo["Job repository"]
  node_sandbox_client["Sandbox client"]
  node_dependency_scan["Dependency scanning"]
  node_dependency_api["Dependency endpoints"]
  node_dependency_repo["Dependency repository"]
end

subgraph group_intel["Threat Intelligence"]
  node_threats["Threat management<br/>[AmeacaService.java]"]
  node_indicators["Threat indicators"]
  node_vulnerabilities["Vulnerability management"]
  node_threat_reports["Threat reporting"]
end

subgraph group_soc["SOC Operations"]
  node_rules["Detection rules"]
  node_blocking["Block policies"]
  node_false_positives["False positives"]
  node_remediation["Remediation"]
  node_pipeline["CI/CD pipelines"]
  node_pipeline_repo["Pipeline repository"]
end

subgraph group_platform["API and Persistence"]
  node_web_users["Web users"]
  node_mysql[("MySQL")]
  node_error_handler["API error mapping"]
end

node_client(("API client"))
node_sandbox_api{{"Sandbox service"}}

node_client -->|"uploads file"| node_sandbox_controller
node_sandbox_controller -->|"starts analysis"| node_sandbox_service
node_sandbox_service -->|"saves file"| node_file_service
node_sandbox_service -->|"creates and updates job"| node_job_service
node_sandbox_service -->|"submits file"| node_sandbox_client
node_sandbox_client -->|"requests analysis"| node_sandbox_api
node_file_service -->|"reads and writes"| node_file_repo
node_job_service -->|"reads and writes"| node_job_repo
node_dependency_api -->|"invokes"| node_dependency_scan
node_dependency_scan -->|"reads and writes"| node_dependency_repo
node_pipeline -->|"reads and writes"| node_pipeline_repo
node_file_repo -->|"persists records"| node_mysql
node_job_repo -->|"persists records"| node_mysql
node_dependency_repo -->|"persists records"| node_mysql
node_pipeline_repo -->|"persists records"| node_mysql

click node_sandbox_controller "https://github.com/wormless-framework/wormless-api/blob/main/src/main/java/com/wormless/controller/SandboxController.java"
click node_sandbox_service "https://github.com/wormless-framework/wormless-api/blob/main/src/main/java/com/wormless/services/SandboxService.java"
click node_file_service "https://github.com/wormless-framework/wormless-api/blob/main/src/main/java/com/wormless/services/ArquivoService.java"
click node_file_repo "https://github.com/wormless-framework/wormless-api/blob/main/src/main/java/com/wormless/repository/ArquivoRepository.java"
click node_job_service "https://github.com/wormless-framework/wormless-api/blob/main/src/main/java/com/wormless/services/AnaliseJobService.java"
click node_job_repo "https://github.com/wormless-framework/wormless-api/blob/main/src/main/java/com/wormless/repository/AnaliseJobRepository.java"
click node_sandbox_client "https://github.com/wormless-framework/wormless-api/blob/main/src/main/java/com/wormless/integrations/sandbox/SandboxCliente.java"
click node_dependency_scan "https://github.com/wormless-framework/wormless-api/blob/main/src/main/java/com/wormless/services/DependenciaScanService.java"
click node_dependency_api "https://github.com/wormless-framework/wormless-api/blob/main/src/main/java/com/wormless/controller/DependenciaScanController.java"
click node_dependency_repo "https://github.com/wormless-framework/wormless-api/blob/main/src/main/java/com/wormless/repository/DependenciaScanRepository.java"
click node_threats "https://github.com/wormless-framework/wormless-api/blob/main/src/main/java/com/wormless/services/AmeacaService.java"
click node_indicators "https://github.com/wormless-framework/wormless-api/blob/main/src/main/java/com/wormless/services/IndicadorAmeacaService.java"
click node_vulnerabilities "https://github.com/wormless-framework/wormless-api/blob/main/src/main/java/com/wormless/services/VulnerabilidadeService.java"
click node_threat_reports "https://github.com/wormless-framework/wormless-api/blob/main/src/main/java/com/wormless/services/RelatorioAmeacaService.java"
click node_rules "https://github.com/wormless-framework/wormless-api/blob/main/src/main/java/com/wormless/services/RegraDeteccaoService.java"
click node_blocking "https://github.com/wormless-framework/wormless-api/blob/main/src/main/java/com/wormless/services/PoliticaBloqueioService.java"
click node_false_positives "https://github.com/wormless-framework/wormless-api/blob/main/src/main/java/com/wormless/services/FalsoPositivoService.java"
click node_remediation "https://github.com/wormless-framework/wormless-api/blob/main/src/main/java/com/wormless/services/RemediacaoService.java"
click node_pipeline "https://github.com/wormless-framework/wormless-api/blob/main/src/main/java/com/wormless/services/PipelineCICDService.java"
click node_pipeline_repo "https://github.com/wormless-framework/wormless-api/blob/main/src/main/java/com/wormless/repository/PipelineCICDRepository.java"
click node_web_users "https://github.com/wormless-framework/wormless-api/blob/main/src/main/java/com/wormless/services/UsuarioWebService.java"
click node_error_handler "https://github.com/wormless-framework/wormless-api/blob/main/src/main/java/com/wormless/exception/GlobalExceptionHandler.java"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_sandbox_controller,node_sandbox_service,node_file_service,node_file_repo,node_job_service,node_job_repo,node_sandbox_client,node_dependency_scan,node_dependency_api,node_dependency_repo,node_client toneBlue
class node_threats,node_indicators,node_vulnerabilities,node_threat_reports toneAmber
class node_rules,node_blocking,node_false_positives,node_remediation,node_pipeline,node_pipeline_repo toneMint
class node_web_users,node_mysql,node_error_handler toneRose
class node_sandbox_api toneIndigo
```

## Components

### File Analysis

- [Sandbox endpoints](https://github.com/wormless-framework/wormless-api/blob/main/src/main/java/com/wormless/controller/SandboxController.java): `src/main/java/com/wormless/controller/SandboxController.java`
- [Analysis orchestration](https://github.com/wormless-framework/wormless-api/blob/main/src/main/java/com/wormless/services/SandboxService.java): `src/main/java/com/wormless/services/SandboxService.java`
- [File validation](https://github.com/wormless-framework/wormless-api/blob/main/src/main/java/com/wormless/services/ArquivoService.java): `src/main/java/com/wormless/services/ArquivoService.java`
- [File repository](https://github.com/wormless-framework/wormless-api/blob/main/src/main/java/com/wormless/repository/ArquivoRepository.java): `src/main/java/com/wormless/repository/ArquivoRepository.java`
- [Job lifecycle](https://github.com/wormless-framework/wormless-api/blob/main/src/main/java/com/wormless/services/AnaliseJobService.java): `src/main/java/com/wormless/services/AnaliseJobService.java`
- [Job repository](https://github.com/wormless-framework/wormless-api/blob/main/src/main/java/com/wormless/repository/AnaliseJobRepository.java): `src/main/java/com/wormless/repository/AnaliseJobRepository.java`
- [Sandbox client](https://github.com/wormless-framework/wormless-api/blob/main/src/main/java/com/wormless/integrations/sandbox/SandboxCliente.java): `src/main/java/com/wormless/integrations/sandbox/SandboxCliente.java`
- [Dependency scanning](https://github.com/wormless-framework/wormless-api/blob/main/src/main/java/com/wormless/services/DependenciaScanService.java): `src/main/java/com/wormless/services/DependenciaScanService.java`
- [Dependency endpoints](https://github.com/wormless-framework/wormless-api/blob/main/src/main/java/com/wormless/controller/DependenciaScanController.java): `src/main/java/com/wormless/controller/DependenciaScanController.java`
- [Dependency repository](https://github.com/wormless-framework/wormless-api/blob/main/src/main/java/com/wormless/repository/DependenciaScanRepository.java): `src/main/java/com/wormless/repository/DependenciaScanRepository.java`

### Threat Intelligence

- [Threat management](https://github.com/wormless-framework/wormless-api/blob/main/src/main/java/com/wormless/services/AmeacaService.java): `src/main/java/com/wormless/services/AmeacaService.java`
- [Threat indicators](https://github.com/wormless-framework/wormless-api/blob/main/src/main/java/com/wormless/services/IndicadorAmeacaService.java): `src/main/java/com/wormless/services/IndicadorAmeacaService.java`
- [Vulnerability management](https://github.com/wormless-framework/wormless-api/blob/main/src/main/java/com/wormless/services/VulnerabilidadeService.java): `src/main/java/com/wormless/services/VulnerabilidadeService.java`
- [Threat reporting](https://github.com/wormless-framework/wormless-api/blob/main/src/main/java/com/wormless/services/RelatorioAmeacaService.java): `src/main/java/com/wormless/services/RelatorioAmeacaService.java`

### SOC Operations

- [Detection rules](https://github.com/wormless-framework/wormless-api/blob/main/src/main/java/com/wormless/services/RegraDeteccaoService.java): `src/main/java/com/wormless/services/RegraDeteccaoService.java`
- [Block policies](https://github.com/wormless-framework/wormless-api/blob/main/src/main/java/com/wormless/services/PoliticaBloqueioService.java): `src/main/java/com/wormless/services/PoliticaBloqueioService.java`
- [False positives](https://github.com/wormless-framework/wormless-api/blob/main/src/main/java/com/wormless/services/FalsoPositivoService.java): `src/main/java/com/wormless/services/FalsoPositivoService.java`
- [Remediation](https://github.com/wormless-framework/wormless-api/blob/main/src/main/java/com/wormless/services/RemediacaoService.java): `src/main/java/com/wormless/services/RemediacaoService.java`
- [CI/CD pipelines](https://github.com/wormless-framework/wormless-api/blob/main/src/main/java/com/wormless/services/PipelineCICDService.java): `src/main/java/com/wormless/services/PipelineCICDService.java`
- [Pipeline repository](https://github.com/wormless-framework/wormless-api/blob/main/src/main/java/com/wormless/repository/PipelineCICDRepository.java): `src/main/java/com/wormless/repository/PipelineCICDRepository.java`

### API and Persistence

- [Web users](https://github.com/wormless-framework/wormless-api/blob/main/src/main/java/com/wormless/services/UsuarioWebService.java): `src/main/java/com/wormless/services/UsuarioWebService.java`
- **MySQL**
- [API error mapping](https://github.com/wormless-framework/wormless-api/blob/main/src/main/java/com/wormless/exception/GlobalExceptionHandler.java): `src/main/java/com/wormless/exception/GlobalExceptionHandler.java`

### Other components

- **API client**
- **Sandbox service**

## Connections

- API client → Sandbox endpoints: uploads file
- Sandbox endpoints → Analysis orchestration: starts analysis
- Analysis orchestration → File validation: saves file
- Analysis orchestration → Job lifecycle: creates and updates job
- Analysis orchestration → Sandbox client: submits file
- Sandbox client → Sandbox service: requests analysis
- File validation → File repository: reads and writes
- Job lifecycle → Job repository: reads and writes
- Dependency endpoints → Dependency scanning: invokes
- Dependency scanning → Dependency repository: reads and writes
- CI/CD pipelines → Pipeline repository: reads and writes
- File repository → MySQL: persists records
- Job repository → MySQL: persists records
- Dependency repository → MySQL: persists records
- Pipeline repository → MySQL: persists records