Documentation
Everything you need to deploy, configure, and scale intelligence-driven malware analysis.
Installation
Local Development Setup
git clone https://github.com/forex911/ACROS.git acros
cd acros/backend
python -m venv venv
# On Windows: venv\Scripts\activate
# On Linux/macOS: source venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
Docker Compose
For a fully containerized environment with all dependencies (MongoDB, Redis, Neo4j, MinIO):
docker-compose up --build -d
Kubernetes Helm Deployment
For production deployments on Kubernetes clusters:
helm repo add acros https://charts.forex911.online
helm install acros-prod acros/acros-platform -n security --create-namespace
Configuration
Backend Environment (.env)
| Variable | Default | Description |
|---|
| MONGO_URI | mongodb://localhost:27017 | MongoDB connection string for metadata |
| DATABASE_NAME | sentinel_ai | Main database name |
| REDIS_URL | redis://localhost:6379 | Redis connection string for PubSub/caching |
| NEO4J_URI | bolt://localhost:7687 | Neo4j Bolt connection URI for attack graphs |
| NEO4J_USER / PASSWORD | neo4j / test1234 | Neo4j authentication credentials |
| S3_ENDPOINT | http://localhost:9000 | MinIO/S3 compatible storage endpoint |
| S3_ACCESS_KEY / SECRET | minioadmin | Object storage credentials for malware payloads |
| SECRET_KEY | - | 32-character secret for JWT signing |
| SUPABASE_URL | - | Supabase endpoint for RBAC and Auth |
| VIRUSTOTAL_API_KEY | - | (Optional) VT API key for IOC enrichment |
| ABUSEIPDB_API_KEY | - | (Optional) AbuseIPDB key for IP reputation |
| ENVIRONMENT | development | Application environment (development/production) |
System Overview
ACROS employs an event-driven microservices architecture leveraging FastAPI for high-throughput routing, isolated execution sandboxes, and a multi-database persistence layer.
Component Flow
User/API -> FastAPI Gateway -> MinIO (Payload) + MongoDB (Metadata)
↓
Celery Worker Pool / Kubernetes Jobs -> Sandbox Engine Selector (gVisor/Firecracker)
↓
Static & Runtime Analysis -> Redis PubSub (Telemetry Streaming)
↓
AI Threat Engine + Intelligence Layer -> Neo4j (Attack Graph) -> Analyst Report
Backend Structure (app/)
- api/routes/: 12 modular FastAPI routers (upload, analysis, jobs, websockets, graph, hunting)
- services/: Core business logic and intelligence processors
- database/: Connection managers for MongoDB, Redis, and Neo4j
- models/ & schemas/: Pydantic validation and database models
- core/: Configuration, exceptions, rate limiting, and observability
Intelligence Layer
Located in app/services/, this layer converts raw telemetry and static findings into actionable, graph-linked threat intelligence.
- analysis_pipeline.py: Orchestrates the full lifecycle from upload to report generation.
- mitre_mapper.py: Maps behavioral capabilities (e.g., registry modifications, process injection) to specific MITRE ATT&CK techniques.
- threat_correlation.py: Correlates disparate runtime events into logical attack chains.
- ioc_pipeline.py: Extracts network and file IOCs and enriches them via external APIs.
- yara_service.py: Scans payloads against community and custom YARA rule sets.
- graph_ingester.py: Constructs Neo4j nodes and edges from the analysis results.
- cross_job_correlation.py: Identifies shared infrastructure across separate analysis jobs.
- hunting_service.py: Provides querying capabilities over historical telemetry and graphs.
AI/ML Engine
Located in the ai_engine/ directory, providing machine learning capabilities separate from the core API.
- XGBoost Classifier: A trained tree-based model providing probability scores for malware family classification based on static and dynamic features.
- Transformer Explainer: Hugging Face LLM integration for generating human-readable executive summaries from structured analysis data.
Sandbox Engines
Configurable execution environments defined in sandbox/engine_selector.py.
- Local Dev: Unisolated execution for local development and testing.
- gVisor (runsc): User-space kernel providing container-level isolation and system call interception.
- Firecracker: AWS-developed microVMs for hardware-level isolation with millisecond startup times.
- Kata Containers: Lightweight virtual machines seamlessly integrated with Kubernetes.
Data Stores
- MongoDB (Motor async): Document store for job metadata, static results, runtime telemetry arrays, and final AI reports.
- Redis: PubSub bus for real-time WebSocket telemetry routing (
job_updates:{job_id}) and distributed caching.
- Neo4j: Graph database storing the relational attack representation (File, Process, NetworkConnection, and IOC nodes).
- MinIO: S3-compatible object storage for secure, content-addressable storage of malware payloads and PCAP files.
Pipeline Workflow
The orchestrator manages the sandbox state machine: PENDING -> STATIC_ANALYSIS -> SANDBOX_RUNNING -> INTELLIGENCE_PROCESSING -> COMPLETED.
Detailed Execution Pipeline
1. Upload & Hash: File stored in MinIO, SHA256 generated.
2. Static Analysis: PE parsing, entropy, strings, YARA scanning.
3. Sandbox Dispatch: Payload deployed to chosen engine (e.g., Firecracker).
4. Runtime Execution: eBPF/sys.addaudithook captures process, network, and file I/O telemetry.
5. Telemetry Streaming: Events published to Redis PubSub and streamed via WebSockets.
6. Capability Extraction: Telemetry parsed to extract IOCs and MITRE techniques.
7. Graph Ingestion: Nodes and edges pushed to Neo4j.
8. AI Reporting: LLM generates executive summary based on aggregated data.
Observability Stack
ACROS is instrumented for enterprise-grade monitoring and SIEM integration.
- OpenTelemetry: Distributed tracing across FastAPI, Celery, and database drivers, exportable to Jaeger or Tempo.
- Prometheus: The
/metrics endpoint exposes application health, job processing durations, and throughput statistics.
- Structured Logging: JSON-formatted logs via
structlog ready for ingestion by ELK or Splunk.