A self-hosted, interactive malware-analysis sandbox for SOC teams.
Detonate a file or URL in a throwaway Windows 11 VM, drive the desktop live in your browser,
and watch the process tree, file, registry, network and DNS activity stream in as it happens.
Features · How it works · Quick start · Progress · Contributing
Warning
MALdex exists to run hostile code. Treat every host it runs on as dedicated to it. Until a maintainer explicitly signs off, only the harmless test files in deploy/guest/samples are run against a real VM: EICAR, a registry-write script, a URL we control, and a benign macro that launches calc.exe.
Hosted sandboxes are fast and polished, but every sample you upload leaves your network. MALdex gives an MSP's SOC the same interactive workflow on infrastructure it controls. We weigh decisions in this order:
- Data sovereignty. Samples, telemetry and results never leave our infrastructure.
- Interactive analysis. Analysts drive the VM live while telemetry streams in.
- Workflow integration. SSO, per-customer org tagging, and later mailbox intake and IOC export.
- Cost.
MALdex is an internal tool, not a commercial product. It is built from a custom .NET control plane on top of open-source components we trust: libvirt/QEMU, Apache Guacamole, mitmproxy, tcpdump, Suricata, YARA, INetSim and Sysmon.
- Files and URLs. Submit Office and PDF documents, PE files, scripts (PowerShell, JS, VBS, HTA, BAT, LNK) and containers, or just a URL.
- Live, interactive desktop. A Guacamole stream into the guest, in the browser, with no plugins. Extend the run, upload another file, reboot or stop.
- Real-time telemetry over SignalR. A process tree plus file, registry, network and DNS events, pushed to the UI while the sample runs.
- Full network capture. A PCAP per run, decrypted HTTP(S) transactions through transparent mitmproxy, and Suricata flow records and alerts.
- Detections and verdicts. YARA on the sample and on every dropped file, Suricata alerts, and behavioral heuristics (Office spawning a script host,
Run/RunOncepersistence, executables dropped and then run). These roll up into Malicious / Suspicious / No threats detected. - Reports. A single HTML report template, also exported to PDF through headless Chromium. It covers the timeline, process tree, network and HTTP activity, detections and screenshots.
- Safe artifact downloads. Samples, dropped files and captures are only ever served as password-protected ZIPs (
infected).
- Throwaway VMs. Each run boots from a copy-on-write overlay of a clean, hardened Windows 11 26H2 image (UEFI + Secure Boot, TPM 2.0). The VM, overlay and network are destroyed when the run ends.
- No route out by default. Each run gets its own L2 bridge with no host IP and a private gateway namespace. nftables drops by default, and host-wide guard tables drop any forwarding to or from run interfaces.
- Network modes.
None,Simulated(INetSim answers everything),LiveVpn(country)through a WireGuard exit, andLiveTor(planned). - Fails closed. If the chosen exit is unavailable, the run fails while it is preparing. It never falls back to direct egress.
- Isolation self-test before every real run. The guest probes the gateway, the host, the LAN and RFC1918 ranges. Detonation only happens if every internal probe fails and the egress IP matches the expected exit.
- No guest networking for the agent. The in-guest agent talks over virtio-serial with framed, size-capped, schema-validated, rate-limited messages. Samples go in and dropped files come out as chunked, SHA-256-verified transfers.
- Local accounts by default, optional OIDC SSO. Built-in users with
AnalystandAdminroles, lockout, optional TOTP and break-glass admins; any OpenID Connect provider (Entra ID, Keycloak, ...) can be added for single sign-on (DevAuthin development). - Org tagging. Every task belongs to a customer org, and each org has its own retention window, enforced by a nightly job.
- Audit log of submissions, downloads, session joins, deletions and admin changes.
- Safe rendering. Guest-derived strings are always shown as text, never as HTML. The SPA and the reports run under a strict CSP.
- Fake mode. The whole product, UI included, runs without a VM in about 3–4 GB of RAM, against a replayed agent.
flowchart LR
A["Analyst browser<br/>React SPA"] -- "HTTPS + SignalR" --> W["Maldex.Web<br/>API · hubs · reports"]
A -- "Guacamole tunnel" --> G["guacd"]
W <--> O["Maldex.Orchestrator<br/>scheduler · VM pool"]
W <--> DB[("SQL Server 2022")]
O -- libvirt --> VM["Windows 11 guest<br/>Maldex.Agent + Sysmon"]
G -- VNC --> VM
VM <-- "virtio-serial" --> O
VM -- "per-run bridge" --> NS["Gateway netns<br/>dnsmasq · mitmproxy · tcpdump"]
NS --> X{"Exit"}
X --> N0["None"]
X --> N1["INetSim"]
X --> N2["WireGuard"]
O --> P["Maldex.Processing<br/>Suricata · YARA · verdict"]
Each task moves through a single, audited state machine:
Queued → Preparing → Running → Collecting → Processing → Completed
│ │ │ │
└───────────┴──────────┴─────────────┴──→ Failed | Cancelled
| Path | What's there |
|---|---|
src/Maldex.Core |
Domain model, lifecycle state machine, scheduler and verdict rules, all pure and unit-tested |
src/Maldex.Data |
EF Core context, configurations and migrations (SQL Server) |
src/Maldex.Infrastructure |
libvirt, networking, Guacamole, the agent channel, storage, scanning, and the dev fakes |
src/Maldex.Orchestrator |
Runs tasks: prepare, detonate, collect, tear down |
src/Maldex.Processing |
Post-run Suricata, YARA, HTTP indexing and verdicts |
src/Maldex.Web |
ASP.NET Core host: API endpoints, SignalR hubs, auth, audit, HTML/PDF reports |
src/Maldex.Agent |
C# guest agent: collectors, commands, isolation probes, file transfers |
ui/ |
React + TypeScript (Vite) SPA |
tests/ |
xUnit unit and integration suites (Testcontainers SQL Server, real-VM E2E behind env gates) |
deploy/guest |
Unattended Windows 11 image build and provisioning, plus the harmless E2E samples |
deploy/net, deploy/host |
INetSim, mitmproxy and Suricata config, and host nftables guard tables |
rules/yara |
YARA rules (indexed through index.yar) |
build.sh |
Every local workflow: setup, run, test, smoke, guest build, E2E |
Prerequisites: Ubuntu 24.04, the .NET 10 SDK, Docker, Node 22 and YARA 4.5. Real mode also needs KVM.
git clone https://github.com/basht0p/Maldex.gitcd Maldex && ./build.sh setupsetup generates .env with a random SQL Server SA password, restores .NET tools and installs Chromium for PDF reports.
./build.sh runThis starts SQL Server in Docker (capped at 2 GB), the backend on http://localhost:5080 and the Vite dev server. Sign-in uses DevAuth, and runs are played back by FakeHypervisor + ReplayAgent, so you get a live process tree, events, verdicts and reports with no Windows guest.
Template jobs (Build, Edit, Refresh) also run in fake mode, but they load the same components as real mode: the guest agent (./build.sh agent) and the mitmproxy CA (.data/mitm/ca/mitmproxy-ca-cert.pem), and a Build also needs the virtio driver ISO (.data/vm/iso/virtio-win.iso). Run ./build.sh real-setup once, or place stubs: any PEM certificate as the CA and an empty file as the virtio ISO (fake mode never reads it):
mkdir -p .data/mitm/ca .data/vm/iso
openssl req -x509 -newkey rsa:2048 -nodes -subj /CN=maldex-dev-ca -keyout /dev/null -out .data/mitm/ca/mitmproxy-ca-cert.pem
touch .data/vm/iso/virtio-win.iso./build.sh real-setupMALDEX_MODE=Real ./build.sh runreal-setup installs libvirt/QEMU, OVMF, swtpm, WireGuard tools, a pinned mitmproxy, Suricata, INetSim and the tools the template Build needs (wimtools, xorriso, libguestfs), and caches the virtio drivers and Sysmon.zip. In real mode, run also starts guacd in Docker for the live view. Then build the guest image in the app: upload or fetch a Windows 11 ISO under Admin → Sandbox Templates → Media, start New template, turn off Tamper Protection and Defender in the job's console, and press Seal. See deploy/guest/README.md for the Build flow, media options and Office. A real run budgets about 9 GB of RAM in total (4 GB / 2 vCPU for the guest).
| Target | What it does |
|---|---|
setup |
Generate .env, restore tools, install Chromium for PDF |
dev-db |
Start SQL Server 2022 in Docker on localhost:14333 |
run |
Dev backend + Vite (MALDEX_MODE=Real for real mode) |
test |
All .NET tests and the UI unit tests |
smoke |
Playwright E2E against the hosted SPA and the fake backend |
build |
Build the SPA into wwwroot and publish Maldex.Web |
real-setup / real-smoke |
Install the real-mode toolchain / boot a throwaway KVM VM to check it |
agent |
Publish the guest agent that templates are built and refreshed with |
e2e |
Harmless real-VM end-to-end suite (needs the default template win11-26h2) |
e2e-templates |
Real template-job E2E (Refresh, Edit, Roll back, Build from MALDEX_WIN_ISO); a green full run writes the validation stamp |
e2e-build-acceptance |
Interactive Build from MALDEX_WIN_ISO: you turn off Defender in the job's console (localhost:5080 over an SSH forward) and press Seal |
Release packages are built and signed by the release workflow: a .deb for Ubuntu 24.04 and an .rpm for RHEL 9 and its rebuilds (x86_64). Maldex assumes a dedicated host: the package creates five system users (maldex, maldex-mitm, maldex-dns, maldex-isroot, maldex-isuser) and a sudoers file that gives the maldex service user passwordless sudo for a fixed list of commands (chmod chown cp find install ip iptables kill mount nft rm setsid sysctl umount), because the app drives libvirt, nftables and network namespaces through sudo -n. Do not install it on a shared machine.
-
Download and verify. Download the
.debor.rpm,SHA256SUMS,SHA256SUMS.ascandmaldex-signing-key.ascfrom the GitHub release, then:gpg --show-keys --with-fingerprint maldex-signing-key.asc gpg --import maldex-signing-key.asc gpg --verify SHA256SUMS.asc SHA256SUMS sha256sum -c SHA256SUMS --ignore-missing
The checksums and signatures only prove the files match the key you imported, so compare the fingerprint printed by
--show-keyswith one you obtained out of band (ask basht0p) before trusting the key. Do not take the fingerprint from the same release page. -
Install.
sudo apt install ./maldex_*.debOn RHEL, first
sudo dnf install epel-releaseand enable the CRB repository (sudo dnf config-manager --set-enabled crb), thensudo dnf install ./maldex-*.rpm. For the rpm you can alsosudo rpm --import maldex-signing-key.ascand check it withrpm -K maldex-*.rpm.RHEL: install INetSim by hand. EL9 has no INetSim package (not in the base repositories, not in EPEL), so the rpm cannot depend on it. Install it from the INetSim release tarball and its Perl dependencies so that
/usr/bin/inetsimand its data directory/var/lib/inetsimexist, then create its system user:sudo useradd --system --user-group --no-create-home --shell /usr/sbin/nologin inetsim.maldex-setupchecks all three. The rpm also links/usr/bin/qemu-system-x86_64to RHEL's/usr/libexec/qemu-kvm, the emulator path the VMs use. -
Configure the database. Edit
/etc/maldex/appsettings.Production.json(mode 0640,root:maldex) and set the SQL Server connection string. Nothing else is required: sign-in uses local accounts, and single sign-on is optional (see Single sign-on). No SQL Server yet? See SQL Server Express on the same host. -
Run the host setup.
sudo maldex-setup
It installs and checks the rest of the host (libvirt/KVM, mitmproxy, guest tooling, Sysmon and the virtio drivers), then restarts maldex and checks that it stays up; if it does not,
journalctl -u maldex -n 50names the problem.maldex-setup --checkre-runs only the read-only checks.First admin. Right after the database check, setup creates the first Maldex admin if no enabled admin exists yet: it asks for a user name (default
admin) and then, without echo, for a password (12 to 256 characters). Run it from a terminal for this. Without one the step fails and prints the command to run yourself:sudo maldex-admin create-user <name> --admin. Re-running setup later does nothing here once an enabled admin exists, andmaldex-setup --checkfails while there is none. Reading the users needs root, so--checkreachesmaldex-adminthroughsudo -n; run as a user without passwordless sudo, itsadminline fails with the exit status instead of a verdict, so runsudo maldex-setup --checkfor that line.Offline. On a host without internet access, copy
Sysmon.zipandvirtio-win.isointo a directory and runsudo maldex-setup --offline <dir>. Offline mode does not cover the OS packages (use a local mirror) or the Playwright Chromium that PDF reports need. To include Chromium, install it on a connected host with the same Maldex version (PLAYWRIGHT_BROWSERS_PATH=$PWD/ms-playwright /opt/maldex/app/Maldex.Web --install-browsers --no-deps) and copy thatms-playwrightdirectory to<dir>/ms-playwright; maldex-setup copies it to/var/lib/maldex/ms-playwright. Without it, setup warns, finishes, and everything except PDF reports works; add Chromium later withsudo maldex-setuponce the host can reach the Playwright CDN. -
Sign in. The app listens on
http://127.0.0.1:5080only; reach it through an SSH forward (ssh -L 5080:127.0.0.1:5080 <host>, then openhttp://127.0.0.1:5080) or a reverse proxy you provide, and sign in with the admin from step 4. Create analyst accounts under Admin → Users (or withmaldex-admin, see below), then build the first guest image under Admin → Sandbox Templates → New template.Behind a TLS reverse proxy, the proxy runs on the same host, forwards to
127.0.0.1:5080and must setX-Forwarded-Proto,X-Forwarded-HostandX-Forwarded-For. Maldex honours these headers only from a loopback client. They decide the cookie'sSecureflag and the single sign-on redirect URI, so without them HTTPS sign-in and SSO break. SSO needs an HTTPS origin unless you use the SSH forward (http://127.0.0.1counts as a secure context in browsers; any other plain-HTTP address is not supported). The sign-in rate limit (10 requests a minute) is kept per client address, so everyone who comes in through an SSH forward shares the one127.0.0.1allowance, and a local process can setX-Forwarded-Forto get a fresh one; the per-account lockout still limits password guessing.
Restarting or upgrading the maldex package, restarting maldex-host-guard, or re-running maldex-setup (which restarts maldex) stops any running analysis VMs; let runs finish first.
Local accounts work with no identity provider. To also let people sign in with a standard OpenID Connect provider (Entra ID, Keycloak, Okta, ...), set Maldex:Auth:Oidc in /etc/maldex/appsettings.Production.json and run sudo systemctl restart maldex. SAML is not supported.
Register Maldex at the provider as a web application with the redirect (callback) URI <origin>/signin-oidc, where <origin> is the URL people open, for example https://maldex.example.com/signin-oidc. Behind a reverse proxy, see the forwarded-header note in step 5 above: the redirect URI Maldex sends is built from X-Forwarded-Proto and X-Forwarded-Host. Maldex uses the authorization code flow with PKCE.
Key (under Maldex:Auth) |
Meaning |
|---|---|
PasswordLogin |
true (default) keeps the password form for everyone. false turns password sign-in off except for break-glass local admins (below). It needs Oidc.Enabled=true, or Maldex refuses to start. |
Oidc.Enabled |
true switches SSO on. Startup then checks the other keys and exits with status 78 and a message if they are wrong. |
Oidc.DisplayName |
The label on the sign-in button ("Sign in with Company SSO"). |
Oidc.Authority |
The issuer URL. It must be https:// and serve /.well-known/openid-configuration. |
Oidc.ClientId / Oidc.ClientSecret |
The registration's client. The secret is optional: without one Maldex acts as a public client (PKCE only), for providers that allow it. The secret sits in the same 0640 root:maldex file as the database password. |
Oidc.Scopes |
Default openid profile email. Add the scope your provider needs to release the role or group claim. |
Oidc.NameClaim |
Claim for the display name, default name (falls back to preferred_username, then email, then sub). |
Oidc.RoleClaim, AdminValues, AnalystValues |
The role mapping, below. |
Who is who. An SSO user is identified by the provider's issuer and sub claim, never by e-mail or user name, so an SSO sign-in never takes over a local account with the same name. Changing Authority therefore creates new users instead of re-binding the old ones.
Roles.
- With a mapping (
RoleClaimset): the provider decides at every sign-in. All values of that claim are read; the user is Admin if any value is inAdminValues, else Analyst if any is inAnalystValues, else the sign-in is refused ("your account has no Maldex role") and audited.AdminValuesmust not be empty. Values are compared exactly: case-sensitive, after trimming spaces. Roles of SSO users are then managed by the provider and cannot be changed in Maldex. - Without a mapping (
RoleClaimempty): a new SSO user starts with no access and sees a "waiting for an administrator" page until an admin grants a role under Admin → Users (ormaldex-admin set-role). Existing users keep their role.
Break-glass admins. With PasswordLogin=false an identity-provider outage would lock everyone out. A break-glass account is a local Admin that may still use a password (and must use TOTP) while password login is off. Create one with sudo maldex-admin create-user <name> --admin --break-glass, or mark an existing local admin with sudo maldex-admin set-break-glass <name> on. The password form stays reachable at /login?local=1 for these accounts. maldex-setup --check warns when password login is off, SSO is on and no break-glass admin exists, and maldex-setup creates the first admin as break-glass when password login is off.
Entra ID example.
-
In the Entra admin center, App registrations → New registration. Choose a single tenant, platform Web, and the redirect URI
https://maldex.example.com/signin-oidc. -
Certificates & secrets → New client secret; copy the secret value.
-
App roles → Create app role twice: display name Maldex Admin, value
Maldex.Admin, allowed member types Users/Groups; and Maldex Analyst with valueMaldex.Analyst. -
In Enterprise applications for the same app, Users and groups, assign people or groups to the roles. (Turn on Assignment required to keep everyone else out.)
-
Configure Maldex:
Keycloak example.
-
In the realm, Clients → Create client: client type OpenID Connect, a client ID such as
maldex, Client authentication on (a confidential client), the standard flow only, and the valid redirect URIhttps://maldex.example.com/signin-oidc. Copy the secret from the Credentials tab. -
Clients → maldex → Client scopes → maldex-dedicated → Add mapper → By configuration → Group Membership: token claim name
groups, Full group path off, add to ID token on. -
Create the groups (for example
maldex-admins,maldex-analysts) and add the users. -
Configure Maldex:
"Maldex": { "Auth": { "Oidc": { "Enabled": true, "DisplayName": "Keycloak", "Authority": "https://keycloak.example.com/realms/<realm>", "ClientId": "maldex", "ClientSecret": "<client secret>", "RoleClaim": "groups", "AdminValues": ["maldex-admins"], "AnalystValues": ["maldex-analysts"] } }}
Accounts are managed in the app under Admin → Users (create users, reset passwords, change roles, disable, clear TOTP, mark break-glass, and the Require TOTP for local accounts switch). maldex-admin does the same from the host and works when nobody can sign in. It must run as root, runs the app as the maldex user against the configured database, and never takes a password as an argument: you are asked twice without echo, or you pipe it in with --password-stdin (one line on stdin).
sudo maldex-admin list [--json]
sudo maldex-admin create-user <name> [--admin|--analyst] [--display-name <text>] [--break-glass] [--password-stdin]
sudo maldex-admin reset-password <name> [--reset-totp] [--password-stdin]
sudo maldex-admin set-break-glass <name> on|off
sudo maldex-admin disable <name> # and: enable <name>
sudo maldex-admin set-role <name> admin|analyst|nonecreate-usermakes a local user (analyst unless--admin); users created here do not have to change their password at first sign-in. Names are 1 to 64 characters of letters, digits and. _ @ -; passwords are 12 to 256 characters.listshows name, kind (local or SSO), role, disabled, TOTP, break-glass and last sign-in;--jsonis for scripts.- Changes that would leave no enabled admin able to sign in are refused (exit status 1), and so is changing the role of an SSO user while a role mapping is configured. Other exit codes: 64 for a usage error, 78 for a configuration or database error. Every change is written to the audit log with no acting user and details starting
via maldex-admin: <command line>.
Recovering a locked-out admin. Five failed attempts lock an account for 15 minutes. Wrong passwords at sign-in, wrong TOTP or recovery codes, and a wrong current password when changing the password or the TOTP settings all count. To get back in right away, or after losing the password or the authenticator, run sudo maldex-admin reset-password <name> --reset-totp (leave out --reset-totp to keep the authenticator). It sets the new password, clears the lockout and ends the user's open sessions within five minutes. If every admin is gone, create a new one with sudo maldex-admin create-user <name> --admin.
Maldex needs a SQL Server database. If your organization already runs SQL Server, ask for an empty database and a login that owns it, and skip this section. Otherwise you can run the free SQL Server 2025 Express edition on the Maldex host itself. Express is limited to 50 GB per database, 4 cores and about 1.4 GB of buffer memory, which is enough for one Maldex host with retention enabled. Maldex creates its tables itself on first start, so you only need an empty database and a login.
Run these steps before step 3 above.
-
Add Microsoft's repositories and install SQL Server and
sqlcmd.On Ubuntu 24.04:
curl -fsSL https://packages.microsoft.com/keys/microsoft.asc | sudo gpg --batch --yes --dearmor -o /usr/share/keyrings/microsoft-prod.gpg curl -fsSL https://packages.microsoft.com/config/ubuntu/24.04/mssql-server-2025.list | sudo tee /etc/apt/sources.list.d/mssql-server-2025.list curl -fsSL https://packages.microsoft.com/config/ubuntu/24.04/prod.list | sudo tee /etc/apt/sources.list.d/mssql-release.list sudo apt-get update sudo apt-get install -y mssql-server sudo ACCEPT_EULA=Y apt-get install -y mssql-tools18 unixodbc-dev
On RHEL 9:
curl -fsSL https://packages.microsoft.com/config/rhel/9/mssql-server-2025.repo | sudo tee /etc/yum.repos.d/mssql-server-2025.repo curl -fsSL https://packages.microsoft.com/config/rhel/9/prod.repo | sudo tee /etc/yum.repos.d/mssql-release.repo sudo dnf install -y mssql-server sudo ACCEPT_EULA=Y dnf install -y mssql-tools18 unixODBC-devel
With SELinux enforcing, you can also
sudo dnf install -y mssql-server-selinuxto run SQL Server confined. -
Configure SQL Server as Express. Generate an
sapassword, run the setup without prompts, then limit SQL Server to loopback and cap its memory. By default SQL Server takes 80% of the host's RAM, which the analysis VMs need.SA_PW="$(openssl rand -base64 24 | tr -d '/+=')Aa1" sudo MSSQL_PID=Express ACCEPT_EULA=Y MSSQL_SA_PASSWORD="$SA_PW" /opt/mssql/bin/mssql-conf -n setup sudo /opt/mssql/bin/mssql-conf set network.ipaddress 127.0.0.1 sudo /opt/mssql/bin/mssql-conf set memory.memorylimitmb 2048 sudo systemctl restart mssql-server systemctl is-active mssql-server
Keep
$SA_PWin your password manager; it is the only administrator login. -
Create the database and the Maldex login. The login owns only the
maldexdatabase. Both passwords reachsqlcmdthrough the environment, so they don't appear in the process list.DB_PW="$(openssl rand -base64 24 | tr -d '/+=')Aa1" SQLCMDPASSWORD="$SA_PW" MALDEX_DB_PW="$DB_PW" /opt/mssql-tools18/bin/sqlcmd -S 127.0.0.1 -U sa -C -b <<'SQL' CREATE DATABASE maldex; GO CREATE LOGIN maldex WITH PASSWORD = '$(MALDEX_DB_PW)', DEFAULT_DATABASE = maldex; GO USE maldex; CREATE USER maldex FOR LOGIN maldex; ALTER ROLE db_owner ADD MEMBER maldex; GO SQL
-
Print the connection string and paste it into
ConnectionStrings:Maldexin/etc/maldex/appsettings.Production.json(step 3 above). Then clear the variables.echo "Server=127.0.0.1,1433;Database=maldex;User Id=maldex;Password=$DB_PW;TrustServerCertificate=True" unset SA_PW DB_PW
TrustServerCertificate=Trueis needed because SQL Server uses a self-signed certificate. The generated passwords contain no;or quotes, which would break the connection string.sudo maldex-setupthen checks that it can reach the database.
SQL Server listens on 127.0.0.1 only, so you don't need to open a firewall port. Back up the database with your usual tooling (BACKUP DATABASE maldex TO DISK = ... through sqlcmd). Express has no SQL Server Agent jobs to schedule this, so use a cron job or systemd timer.
MALdex is delivered in sub-projects. Sub-project 1, the core detonation slice, is code complete and runs green end to end on a real Windows 11 guest.
| Milestone | Status |
|---|---|
| Design spec for the core detonation slice | ✅ Approved |
| Plan 1a: fake-mode slice (submit → live tree → verdict → HTML/PDF report → ZIP downloads → retention) | ✅ Complete |
| Plan 1b: real mode (libvirt, guest image, per-run networking, capture, isolation self-test, live view) | ✅ Merged (#3, #4, #5) |
| Pre-live hardening (capability-free dnsmasq, per-run PID namespace for INetSim) | ✅ Merged (#6) |
| First real-VM E2E on Windows 11 (EICAR, registry write, URL) | ✅ Green (#7) |
| Brand identity: Magic Bytes mark, icons, design tokens | 🟦 In review (#2) |
| Containerized deployment with one-command install | 🟦 In review (#1) |
| Office in the guest image (benign calc-macro scenario) | ⬜ Planned |
| Edge first-run suppression for URL runs | ⬜ Planned |
| Per-run uids for dnsmasq/mitmdump, then more than one concurrent VM | ⬜ Planned |
| First live-malware detonation | 🔒 Needs maintainer sign-off |
- Next sub-projects: phishing mailbox intake (Microsoft 365, Graph API) with automated runs. IOC extraction and export (STIX, MISP, SIEM).
- Later: Sigma, capa and other static analysis, threat-intel enrichment, Tor and multi-country exits, Linux guests, multiple KVM hosts, memory forensics, CI.
- Not planned: Android, or sharing samples or results outside our infrastructure.
Target scale: 10–12 concurrent runs and about 100 runs a day at peak, mostly interactive, on a single host.
Contributions from the team are welcome. MALdex handles live malware, so a few rules here are stricter than usual. Please read this whole section before your first PR.
- Never commit malware. No live samples, no PCAPs from real detonations, no dumps. The only samples in the repo are the harmless files in
deploy/guest/samples. If you need a new test case, make it harmless and describe its expected outcome there. - No live detonations without sign-off. Real-VM work uses the harmless samples until a maintainer explicitly approves live malware on a given host.
- Isolation is not negotiable. Changes to networking, nftables, the agent channel or the self-test must keep egress failing closed and must never add a route from a guest to the host, the control plane or the LAN. Call these changes out in your PR description.
- Guest data is hostile. Anything that came from the guest (command lines, filenames, URLs, HTTP bodies) is rendered as text, size-capped and validated. Never render it as HTML or execute it on the host.
- No secrets in git.
.envand anything under.data/stay local.
-
Talk first for anything sizable. Open an issue describing the problem and your proposed design before writing a lot of code. Features start from a short design note, then a plan, then code.
-
Branch from
main. Use a descriptive name such asfeat/ioc-exportorfix/agent-frame-cap. -
Test-driven. Write the failing test first, then make it pass. Pure logic (state machine, scheduler, verdict rules, frame parsing) belongs in
Maldex.Corewith unit tests. Behavior across components gets an integration test against the fakes. -
Keep fake mode working. Every feature has to run with
FakeHypervisorandReplayAgent. Real-VM tests stay behind theMALDEX_REAL_VM/MALDEX_REAL_NETgates. -
Run the checks locally. There is no hosted CI on purpose. Before you open a PR, run:
./build.sh test./build.sh smoke
If your change touches the hypervisor, the guest, networking or the agent and you have a KVM host, run
./build.sh e2etoo and paste the result into the PR. -
Open a PR to
main. Say what was true before, what's true after, how you verified it, and anything you deliberately left out. Keep PRs focused, since smaller ones get reviewed faster. A maintainer reviews and merges.
- Commits follow Conventional Commits with a scope:
feat(processing): …,fix(agent): …,test(real): …,build(deploy): …. Describe the behavior change, not the edit. - C#: nullable reference types are on and warnings are errors (
Directory.Build.props). Package versions live centrally inDirectory.Packages.props. Don't pin versions in project files. - TypeScript: Vitest + React Testing Library for components, and
npm --prefix ui run lint(oxlint) before pushing. - Resources: keep the dev loop light. Fake mode should stay around 3–4 GB of RAM, and real mode runs one VM.
- UI: use the Magic Bytes design tokens. Accent blue is only for things a user can act on. Status colors describe analysis state, and severity is never shown by color alone.
If you find a way for a guest to reach the host, the control plane or the LAN, or any other sandbox escape or isolation gap, don't open a public issue. Contact the maintainer (@basht0p) privately, and stop running real VMs on the affected host until it's fixed.
Licensed under the Apache License 2.0.
MALdex is written almost entirely by AI coding agents. Every design, plan and change is closely overseen by a Security Engineer with years of professional, non-AI software development experience, who reviews and approves everything before it merges.
4D 5A · Built for the SOC, kept on our own metal.