credkellar/sandbox-api repository overview

⁠🧪 sandbox-api

Safely detonate files across PC, mobile, and cloud environments with AI-driven threat reports. Short description — verified live on Docker Hub, 94 / 100 characters.

⁠📖 What is this?

sandbox-api is an automated cross-platform security analysis engine.

It safely detonates suspicious files across PC, mobile, and cloud environments while capturing execution telemetry, network traffic, file system diffs, API traces, and memory dumps. An integrated multi-LLM engine (Gemini, Claude, ChatGPT, Codex) synthesizes captured execution telemetry into structured threat reports.

Instead of running an unknown file on a real machine and hoping for the best — or reading a binary statically and guessing what it would do — you give the file to the sandbox, it executes in an isolated environment built for that platform, everything it does is recorded, and the recordings are turned into a readable, structured verdict.

Verified live on Docker Hub (2026-10-31):

⁠🧰 Tech Stack Badges & Architecture

⁠⚙️ Workflow Badges — Updated

⁠💻 Core Programming Languages & Core Systems

⁠⛓️ Web3 & Infrastructure

⁠⚙️ Platform Support & Hardware Architecture

⁠⚡ Low-Level Infrastructure & Performance

• Execution telemetry — what the sample actually did when it ran, not what it looks like statically
• Network traffic capture — connections, destinations, and payload behaviour during detonation
• File system diffs — created / modified / deleted files, before vs. after
• API traces — the system/API calls the sample made while executing
• Memory dumps — in-memory artefacts that never touch disk and evade static scanning

⁠🛠️ DevOps & Build Tools

⁠☁️ Cloud Providers

⁠🎯 What this does — Step-by-step

1. Submit — you hand the API a suspicious file. You never execute it on your own machine.
2. Select environment — the engine picks the matching detonation environment: PC, mobile, or cloud.
3. Isolate — the sample is placed in a disposable, isolated sandbox built for that platform.
4. Detonate — the file is executed inside the sandbox, under observation, for its run window.
5. Capture execution telemetry — process behaviour and runtime activity are recorded as it happens.
6. Capture network traffic — every connection the sample attempts is logged.
7. Diff the file system — the environment is compared before / after: what was created, changed, dropped, or deleted.
8. Trace API calls — the sample's API/system-call trace is recorded in order.
9. Dump memory — memory artefacts are captured for payloads that live only in RAM.
10. Synthesize — the multi-LLM engine (Gemini, Claude, ChatGPT, Codex) reads the captured telemetry.
11. Report — you get a structured threat report: what the file did, what it reached for, and what it left behind.
12. Destroy — the detonation environment is disposable; the contaminated sandbox does not become your problem.

⁠✨ Why is this cool? — 10 reasons

1. Detonate first, trust later — unknown files run in a sandbox, never on your real machine.
2. One engine, three worlds — PC, mobile, and cloud samples in a single API instead of three separate toolchains.
3. Behaviour over appearance — it judges a file by what it does, catching malware that looks clean statically.
4. Five evidence streams at once — telemetry, network, FS diffs, API traces, and memory dumps, captured together.
5. Memory doesn't hide — in-memory-only payloads are dumped, not missed.
6. AI writes the boring part — four LLM families (Gemini, Claude, ChatGPT, Codex) turn raw telemetry into a readable report.
7. Structured, not screenshots — reports come out structured, so they can be filed, searched, diffed, and automated on.
8. Proven in the wild — 8,389 pulls and 136 published builds; this is a working, iterated tool, not a demo.
9. One pull to run — the whole detonation stack ships as a single Docker image.
10. Disposable by design — every run burns its environment; no contaminated “analysis VM” slowly rotting on your network.

⁠🛡️ What problems this solves? — 10 solutions

⁠🚀 How to install this — Step by step

1. Install Docker — Docker Engine / Docker Desktop on a linux/amd64 host (or an amd64 VM).

2. Pull the newest build — use :main, not :latest:

   docker pull credkellar/sandbox-api:main
   

   Copy

   (docker pull credkellar/sandbox-api gets :latest — the older 2026-08-25 build.)

3. Or pin an exact build (recommended for reproducibility — 136 tags exist):

   docker pull credkellar/sandbox-api:sha-08214e2
   # replace with the sha-… tag you want from the Tags tab
   

   Copy

4. Check what the image expects before first run:

   docker image inspect credkellar/sandbox-api:main
   docker run --rm credkellar/sandbox-api:main --help
   

   Copy

   The Hub page does not publish an entrypoint, port, or env-var list — verify them from the image / your source build instead of guessing them.

5. Run it — isolated:

   docker run --rm --name sandbox-api credkellar/sandbox-api:main
   # add the -p <port>:<port> mapping and -e KEY=value variables
   # your build documents, once verified in step 4
   

   Copy

6. Or run it with Docker Compose:

   services:
     sandbox-api:
       image: credkellar/sandbox-api:main
       container_name: sandbox-api
       restart: unless-stopped
       # ports:    # add only the port verified in step 4
       #   - "8000:8000"
       # environment:  # add only the keys your build requires, see Requirements
       #   - GEMINI_API_KEY=${GEMINI_API_KEY}
       #   - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
       #   - OPENAI_API_KEY=${OPENAI_API_KEY}
   

   Copy

   docker compose up -d
   docker compose logs -f sandbox-api
   

   Copy

7. Submit a sample and read the report — send a test file (start with a known-harmless test file, e.g. the EICAR test string file) through the API, confirm you get a structured threat report back, then use real samples — only samples you own or are authorised to analyse.

8. Update:

   docker pull credkellar/sandbox-api:main
   docker compose up -d
   

   Copy

⁠📋 Requirements

⁠🌳 FULL Project Structure Tree

sandbox-api/
│
├── A. DOCKER HUB — VERIFIED (2026-10-31)
│   ├── credkellar/sandbox-api          # public, active — 8,389 pulls, 1 star
│   ├── Tags (136)
│   │   ├── main                        # NEWEST — 487 MB, linux/amd64, 2026-09-30
│   │   ├── latest                      # OLDER — 533 MB, linux/amd64, 2026-08-25 ⚠️
│   │   └── sha-… × 134                 # per-build CI tags, e.g. sha-08214e2
│   ├── Short description (94 chars)    # “Safely detonate files across PC, mobile,
│   │                                   #   and cloud environments with AI-driven
│   │                                   #   threat reports.”
│   ├── Full description                # replaced by this overview
│   └── Categories                      # Languages & frameworks · Internet of
│                                       # things · Monitoring & observability
│
└── B. LOGICAL SERVICE STRUCTURE — FROM THE HUB DESCRIPTION
    ├── 📥 Intake / API
    │   └── Sample submission — suspicious file in, report out
    ├── 🧪 Detonation Environments
    │   ├── 🖥️ PC environment
    │   ├── 📱 Mobile environment
    │   └── ☁️ Cloud environment
    ├── 📡 Capture Layer
    │   ├── Execution telemetry
    │   ├── Network traffic capture
    │   ├── File system diffs (before / after)
    │   ├── API traces
    │   └── Memory dumps
    ├── 🤖 Multi-LLM Report Engine
    │   ├── Gemini
    │   ├── Claude
    │   ├── ChatGPT
    │   └── Codex
    ├── 📄 Structured Threat Reports
    │   └── Behaviour · network · file system · API · memory — in one report
    └── 🐳 Delivery
        ├── Dockerfile-built image → Docker Hub (credkellar/sandbox-api)
        ├── CI publish pipeline (sha-… tag per build)
        └── Docker Compose run example (see Install)

⁠⚠️ Honest Status & Safety

• This image executes untrusted files by design. That is its job — and its risk. Isolation is not optional: dedicated host/VM, segmented network, no production data.
• Analyse only samples you own or are authorised to test.
• The Hub page publishes no source repo, entrypoint, port, env-var list, or licence — every such detail above is either verified from the Hub API or explicitly marked unverified.
• latest ≠ newest. Use :main or a pinned sha-… tag.

⁠🔗 Links

• Docker Hub: https://hub.docker.com/r/credkellar/sandbox-api⁠
• Pull: docker pull credkellar/sandbox-api:main