Inspect suspicious files locally through PE analysis, strings, entropy, YARA, IOC extraction, assembly triage, and explainable reporting — without intentionally executing the sample.
Download · Features · Security · Documentation · Report a bug
Warning
AsphDex is beta software. It is suitable for controlled defensive triage and feedback, but features may be incomplete or change without notice. False positives and false negatives are expected. Do not use AsphDex as the sole basis for a security, incident-response, or legal decision.
┌── PE / COFF ─────────────┐
├── Strings & IOCs ────────┤
FILE ──► Fingerprinting ─┼── Entropy ───────────────┼──► Findings ──► Reports
├── YARA ──────────────────┤
└── Assembly triage ───────┘
AsphDex is a desktop-oriented static analysis tool for defensive research, malware triage, education, and controlled laboratory use. It inspects files without intentionally executing them and keeps the primary analysis workflow on the device.
Current release channel: Beta Current version: 0.3.0-beta.4
The current prerelease is available from the GitHub release page. It includes Linux AppImage/Debian packages, clearly labeled unsigned Windows beta artifacts, and platform-specific SHA-256 manifests.
The project is ready for wider controlled testing, but it is not yet a production security product. During the beta period:
- analysis results and risk scores may be incorrect;
- parsers may fail on malformed, packed, signed, or uncommon binaries;
- some interface actions may be incomplete or may regress between builds;
- report schemas, storage formats, and YARA behavior may change;
- backward compatibility is not guaranteed;
- updates may temporarily remove or replace existing functionality.
Please report reproducible problems through GitHub Issues.
This beta candidate strengthens the local-state boundary and verifiable release path:
- JSON state updates use exclusive random staging and serialized IPC mutations, preventing linked-file writes and lost updates across history, settings, caches, rule state and quarantine metadata;
- folder scans visibly report when the 200-file queue limit truncates a selected directory;
- regression tests cover linked state-file targets, failed and concurrent replacements, concurrent history updates and queue-limit reporting;
- GitHub Actions use immutable reviewed pins, supported Node 24 action generations and pinned
cargo-auditfor Rust dependency checks; - Windows NSIS/portable and Linux AppImage/Debian release paths build from the same tag, publish SHA-256 checksums, SPDX SBOMs and provenance attestations.
- the release evidence gate normalizes Windows CRLF checksum entries before attestation lookup.
- malformed PE/ELF worker recovery, 32 MiB bounded analysis soak coverage and packaged renderer smoke checks are included in the beta validation path;
- the analysis flow now shows active-file context, elapsed time and staged progress, with keyboard-safe dialogs, bilingual queue feedback and clearer upload limits;
- run
npm run preflight:betafor the complete local beta gate; the detailed Windows/Linux package and GUI test matrix is in docs/TESTING.md.
The application does not provide dynamic analysis or cloud verdicts by default. Local audits found no known high-severity npm dependency vulnerabilities; this is not a guarantee that the application contains no defects. Unsigned Windows beta builds are for manual installation and manual updates only; trusted automatic updates remain limited to verified signed builds.
| Module | Status | Purpose |
|---|---|---|
| File intake and drag-and-drop | Available | Loads a sample for static inspection |
| MD5, SHA-1, SHA-256 and import hash | Available | Produces file fingerprints |
| PE/COFF parser | Experimental | Displays headers, sections, imports and exports |
| Heuristic risk score | Experimental | Groups related static evidence, applies category caps and evidence floors, then produces a 0–100 triage score |
| Explainable scoring and ATT&CK mapping | Experimental | Shows score evidence, calibration metadata, qualitative false-positive sensitivity and candidate MITRE ATT&CK techniques |
| Session analysis comparison | Available | Compares two completed analyses across hashes, PE metadata, imports, strings, entropy, YARA, IOCs and risk evidence |
| Background analysis and cancellation | Available | Keeps heavy core analysis off the UI thread and reports staged progress |
| PE security metadata | Experimental | Extracts mitigations, TLS/debug indicators, resources, overlay data and signature status |
| String extraction | Available | Extracts ASCII/UTF-16 text, URLs, IPs, paths and suspicious commands |
| IOC report exports | Available | Exports normalized indicators as CSV or STIX 2.1 JSON |
| Entropy analysis | Experimental | Highlights high-entropy files and sections |
| YARA scanning | Experimental | Uses bundled local rules plus a bounded custom-rule editor with native validation and safe .yar/.yara import/export |
| Assembly preview | Experimental | Performs lightweight x86/x64 entry-point triage; it is not a full disassembler |
| Offline hash intelligence | Limited | Currently contains only a small safe test-oriented dataset |
| Scan history | Available | Stores recent scan summaries on the device |
| Encrypted quarantine copy | Experimental | Stores an AES-256-GCM encrypted copy only after binding it to the analyzed size/SHA-256, verifies restored bytes, and does not delete the original file |
| Reports | Available | Exports JSON, TXT, standalone HTML, PDF, IOC CSV and STIX 2.1 with a bounded executive summary and prioritized evidence |
| VirusTotal hash lookup | Optional | Sends only the SHA-256 hash when the user supplies an API key |
| Desktop settings and demo | Available | Persists theme, language and update preferences; includes inert demo samples |
| Crash diagnostics | Available | Keeps local renderer/main-process logs and Chromium crash dumps |
| Windows installer and updates | Experimental | Builds NSIS/portable artifacts and checks configured GitHub Releases |
| Linux packages | Experimental | Builds AppImage and Debian artifacts with the native Rust/YARA-X engine |
AsphDex is designed for static inspection. The application does not intentionally launch or execute the selected sample. This does not make malware handling risk-free.
- Use a dedicated virtual machine for real malware samples.
- Disable or tightly control networking in the analysis environment.
- Use snapshots and disposable storage.
- Do not restore quarantined samples onto a daily-use system.
- Treat every extracted string, report, and detection as untrusted data.
- Keep third-party YARA rules under review before enabling them.
- Treat YARA matches as triage evidence, not malware verdicts. Rule
confidencedescribes confidence that the pattern is present;severitydescribes its security significance. - UPX packing, anti-debugging APIs, and VM-awareness are common in legitimate software and do not imply malware by themselves.
- Windows 10 or Windows 11, x64
- Linux x64 with a recent desktop environment (experimental)
- Node.js 22 or newer for source builds
- npm
git clone https://github.com/dRafaleD/Malware-analysis-AsphDex.git
cd Malware-analysis-AsphDex
npm install
npm test
npm startYou can also run baslat.bat after installing dependencies.
npm run distThis creates both an interactive NSIS installer and a portable build under dist/. Local development builds are named:
AsphDex-0.3.0-beta.4-win-x64-installer.exe
AsphDex-0.3.0-beta.4-win-x64-portable.exe
The public unsigned beta release uses an explicit suffix:
AsphDex-0.3.0-beta.4-win-x64-unsigned-installer.exe
AsphDex-0.3.0-beta.4-win-x64-unsigned-portable.exe
Build either target separately with:
npm run dist:installer
npm run dist:portableOn Linux, build AppImage and Debian packages with:
npm run dist:linux
# or separately:
npm run dist:appimage
npm run dist:debLinux uses the bundled Rust/YARA-X engine directly, so it does not require the Windows YARA executables or a Windows code-signing certificate. Windows uses the bundled YARA executables and Authenticode-specific metadata where available.
These commands produce unsigned development artifacts. For a production build with a code-signing certificate configured in CSC_LINK and CSC_KEY_PASSWORD, use:
npm run dist:signedProduction signing uses electron-builder's standard environment variables. Keep the certificate outside the repository. When both secrets are configured, the release workflow signs and verifies every Windows executable:
$env:CSC_LINK = 'C:\secure\AsphDex-Code-Signing.pfx'
$env:CSC_KEY_PASSWORD = '<certificate-password>'
npm run dist:signedThe same signing identity must be used for every update release so Electron can verify the downloaded installer. The updater requires a generated publisherName, rejects unsigned update metadata, disables web installers and downgrade paths, and only enables installation after a downloaded update has passed electron-updater's Authenticode verification. .env.example documents variable names only; never commit real values.
Before creating a signed Windows production, beta or release-candidate tag, add these repository secrets under GitHub → Settings → Secrets and variables → Actions:
| Secret | Value |
|---|---|
CSC_LINK |
Base64-encoded contents of the .pfx/.p12 certificate, without line breaks |
CSC_KEY_PASSWORD |
Password protecting the certificate |
On PowerShell, create the value for CSC_LINK with:
[Convert]::ToBase64String([IO.File]::ReadAllBytes('C:\secure\AsphDex-Code-Signing.pfx')) | Set-ClipboardPaste the clipboard value into the CSC_LINK secret. Do not put the certificate,
password, base64 value or a personal access token in the repository, workflow
file, issue tracker or release notes. The release workflow uses the certificate
only during the Windows build, verifies Authenticode signatures on every
generated .exe, and stops if the signing configuration is partial or any
signature is invalid. If both secrets are absent, alpha/beta tags publish only
clearly named unsigned Windows artifacts without update metadata; RC and stable
Windows releases still require signing. The certificate subject becomes the updater's trusted
publisherName; all future Windows updates must use the same signing identity.
The updater reads GitHub Releases for dRafaleD/Malware-analysis-AsphDex. Set a release token only in the build environment and publish a draft release with:
$env:GH_TOKEN = '<github-release-token>'
npm run releaseReview the generated release, checksums and signatures before publishing it. Automatic checks are disabled in source/development mode and in unsigned Windows packages.
The repository includes GitHub Actions validation for both Windows and Linux.
Linux CI builds the AppImage and Debian packages and uploads them as a
short-lived workflow artifact for review. A tagged release prepares the GitHub
Release after validation and CodeQL, then Linux and Windows build/upload jobs
run independently. Missing Windows signing secrets therefore do not block Linux.
Configure CSC_LINK and CSC_KEY_PASSWORD repository secrets only for signed
Windows production artifacts.
Tagged releases built from this revision onward include a deterministic SPDX
2.3 dependency inventory generated from the committed npm and Cargo lockfiles.
Tagged releases from 0.3.0-beta.3 onward include this evidence gate. GitHub Actions creates
Sigstore-backed SLSA provenance and SPDX SBOM attestations for the executable
packages. A final release job downloads the public assets again, rejects mixed
signed/unsigned Windows sets, validates both SBOM documents, checks every
published SHA-256 entry, and verifies that GitHub attestations came from this
repository's release workflow.
Consumers can verify provenance and the attached SPDX statement with GitHub CLI:
gh attestation verify <artifact> --repo dRafaleD/Malware-analysis-AsphDex
gh attestation verify <artifact> --repo dRafaleD/Malware-analysis-AsphDex --predicate-type https://spdx.dev/Document/v2.3Artifact attestations establish build origin and integrity; they do not prove that an artifact is vulnerability-free or safe to execute.
Each build also creates assets/native-checksums.json. Before AsphDex launches its bundled Rust engine or YARA binaries, it verifies their SHA-256 values against this manifest. Signed production builds protect both the application archive and this integrity manifest.
YARA rule updates are disabled by default. A release maintainer must configure assets/yara-update-config.json with an HTTPS manifest URL, an explicit hostname allowlist and an Ed25519 public key. The signed manifest supplies a version, HTTPS rule-bundle URL, SHA-256 checksum and publication timestamp; the application verifies the signature and checksum before atomically replacing its local main.yar. ZIP archives, redirects, arbitrary hosts and unsigned rule files are not accepted.
The editor accepts at most 30 rules and 256 KB of UTF-8 source. Validate, Save, Import, and Export compile the source with the platform's native YARA engine before accepting it. Imported files must be regular .yar/.yara files; include directives, duplicate rule names, linked filesystem objects, and oversized sources are rejected. Missing metadata remains visible as a warning and receives conservative scoring defaults rather than being treated as trusted rule quality.
Bundled rules are separated into generic, packer, and suspicious-behavior directories; custom and individually reviewed community rules remain separate. Bundled metadata distinguishes detection confidence from security severity, and missing metadata on custom/community rules receives conservative defaults. The built-in set is regression-tested against local benign references. Broad third-party collections are not bundled wholesale.
The bundled configuration deliberately contains no endpoint or key. Do not enable this channel until its publishing process signs the canonical JSON representation of the signed object with its keys sorted lexicographically.
test/corpus/ contains a small, labeled, inert corpus covering benign notes,
scripted loaders, remote command patterns, process injection, persistence and
network artefacts without storing executable malware. npm run test:corpus
measures the expected benign and suspicious outcomes; CI and tagged releases
enforce this baseline. It is a regression guard, not a claim of real-world
detection coverage.
npm run test:soak runs 24 sequential inert analyses in isolated workers,
checks deterministic hashes and bounded retained ArrayBuffer memory, then
terminates an active large-file analysis and verifies that a fresh worker can
complete the next analysis. Windows and Linux CI run these checks before
packaging or publishing a release.
Security automation also runs npm run audit:secrets, CodeQL extended queries
and weekly Dependabot checks for npm, Cargo and GitHub Actions. Packaged Electron
builds disable Node runtime/inspector environment switches, enable cookie and
supported-platform ASAR integrity protections, and restrict renderer-opened
external links to the explicit VirusTotal HTTPS host. See
THREAT_MODEL.md for trust boundaries and residual risks.
All external GitHub Actions are pinned to reviewed 40-character commit SHAs. Checkout, Node setup and artifact upload use Node 24 action generations; version comments remain beside each pin so Dependabot updates can be reviewed without silently returning to mutable major-version or branch references.
Important
Unsigned Windows alpha/beta artifacts include unsigned in their filenames, may trigger SmartScreen/security warnings and never enable trusted automatic updates. Signed Windows artifacts require both GitHub signing secrets and valid Authenticode verification. Linux packages are currently unsigned; verify their checksums and build from source when trust is critical.
Build outputs and node_modules/ are intentionally excluded from Git. Publish binaries through GitHub Releases instead of committing them to the repository.
npm test
npm run test:memory
npm run preflight:betanpm run test:memory hashes a generated 120 MiB inert buffer with the JavaScript fallback implementation and reports elapsed time, peak resident memory and retained ArrayBuffer memory. It is a local benchmark rather than a universal hardware pass/fail threshold.
On Windows, validate the real packaged application and bundled Rust engine with:
npm run test:packagedThis creates a temporary unpacked build, launches AsphDex.exe in smoke-test mode, verifies the renderer/preload bridge and checks that resources/engine/engine.exe is present. The temporary build is removed when the test finishes.
To exercise the Rust engine protocol directly across all supported commands, run:
npm run test:engineThe automated suite validates the parser helpers, report generation, hash intelligence, assembly triage, YARA output handling, and safe signature fixtures. Tests must not execute real malware.
Safe custom marker:
ASPHDEX-CUSTOM-TEST-MALWARE-12345
The repository keeps only inert EICAR fragments for documentation; tests build safe markers in memory when needed. EICAR is not malware, but antivirus products may intentionally flag or quarantine an exact marker.
- Static analysis and bundled YARA scans are performed on the device.
- Selected files are not uploaded by the core analysis workflow.
- VirusTotal integration is opt-in and submits only a SHA-256 hash.
- The VirusTotal API key remains in the active application session and is not committed to the repository.
- Scan history and encrypted quarantine data are stored in the current operating-system user profile.
- When privacy mode is disabled, up to 20 analysis results may be cached for seven days and keyed only by SHA-256. The cache is restricted to the current application version; privacy mode clears it and prevents new cache entries.
- The threat score is heuristic and is not an antivirus verdict.
- YARA can detect only behavior or signatures represented by enabled rules.
- The PE parser may reject or partially parse damaged and unusual samples.
- Assembly output is a bounded preview and may lose instruction alignment.
- No dynamic analysis, sandbox execution, memory inspection, or network capture is performed.
- Quarantine creates an encrypted copy; it does not automatically remove the source file.
- Automatic update rollback is not implemented; retain the previous signed installer for manual recovery.
See USER_GUIDE.md for safe first-run, demo, report, settings, update and troubleshooting instructions. See CHANGELOG.md for the beta-candidate change record.
AsphDex is provided solely for lawful defensive security research, education, malware triage, and analysis of files you are authorized to inspect.
You are responsible for:
- complying with all applicable laws, regulations, licenses, and organizational policies;
- obtaining authorization before analyzing, retaining, transferring, or restoring a sample;
- isolating potentially malicious files and protecting third parties from harm;
- independently validating every result produced by the application.
The software is provided “AS IS”, without warranty of any kind. To the maximum extent permitted by applicable law, the authors and contributors are not liable for data loss, system damage, security incidents, false positives, false negatives, interrupted operations, legal claims, or any direct, indirect, incidental, special, exemplary, or consequential damages arising from use of the software.
Nothing in this project constitutes legal advice, professional incident-response advice, or a guarantee that a file is safe or malicious.
Beta-stage contributions are welcome. Before opening a pull request:
- keep changes focused and explain the security impact;
- add or update automated tests;
- do not commit live malware, credentials, API keys, personal data, build outputs, or dependency folders;
- document changes that affect reports, storage, YARA rules, or risk scoring;
- run
npm testsuccessfully.
For security-sensitive reports, follow SECURITY.md instead of publishing exploit details in a public issue.
AsphDex is distributed under the ISC License. Third-party components, including Electron and YARA, remain subject to their respective licenses.
The phased development plan is maintained in ROADMAP.md.