gokdogan 🦅

Static PE malware triage engine. Feed it a Windows executable; it extracts static features — hashes, imphash, per-section entropy, packer artifacts, classified strings, import-based capability tags, YARA matches — and produces a transparent, weighted triage verdict: LIKELY_CLEAN, SUSPICIOUS, or HIGH_RISK.

gökdoğan is Turkish for the peregrine falcon — the fastest hunter in the sky. A fitting name: triage is about speed, deciding in seconds which samples deserve a full analyst's attention. (The package and command are the ASCII gokdogan.)

⚠️ Triage, not conviction. gokdogan never executes the sample and its verdict is a prioritization signal, not a definitive classification. Handle real malware only inside an isolated analysis VM.

📐 Architecture: ARCHITECTURE.md (English) · MIMARI.md (Türkçe) · live visual page ↗ (source)

What it does

            ┌────────────────────────────────────────────────┐
            │                  gokdogan                     │
 sample.exe │  ┌──────────┐  ┌─────────┐  ┌──────────────┐   │
 ──────────▶│  │ loader   │─▶│ packers │  │ strings_ext  │   │
            │  │ pefile   │  │ entropy │  │ classifier   │   │
            │  └────┬─────┘  └────┬────┘  └──────┬───────┘   │
            │       │             │              │           │
            │       ▼             ▼              ▼           │
            │  ┌──────────────────────────────────────────┐  │
            │  │ capabilities (API → behavior)  +  YARA   │  │
            │  └───────────────────┬──────────────────────┘  │
            │                      ▼                         │
            │            verdict (weighted score)            │
            └──────────────────────┬─────────────────────────┘
                                   ▼
                     console report  +  JSON export

Install

On any Windows PC — no Python needed

Grab a binary from the Releases page:

• gokdogan-setup.exe — installer. Per-user (no admin prompt), optionally adds gokdogan to your PATH, registers an uninstaller.
• gokdogan.exe — standalone single-file CLI. Copy it anywhere and run it.

Both embed Python, every dependency, and the bundled YARA rules. Build them yourself with .\packaging\build_exe.ps1 (PyInstaller) and ISCC.exe packaging\gokdogan.iss (Inno Setup); pushing a v* tag builds and attaches both to a GitHub Release automatically.

From source

pip install -e .[dev]

Hard dependencies are pefile and ppdeep (pure-Python ssdeep — no C toolchain). Optional: yara-python for the YARA stage and py-tlsh for TLSH fuzzy hashing — each degrades to a note in the report when absent.

pip install -e .[dev,tlsh]   # include TLSH (needs a C++ compiler)

Or run it in a container (no host Python needed):

docker build -t gokdogan .
docker run --rm -v "$PWD/samples:/samples:ro" gokdogan /samples/suspect.exe

The bundled YARA rules ship inside the package, so gokdogan works out of the box; point --rules at your own directory to add your team's rules.

Prefer a browser? Run the optional upload-and-triage web service (drop a PE, get the HTML report; POST /api/triage returns JSON):

pip install -e ".[web]"
uvicorn gokdogan.web:app --host 127.0.0.1 --port 8000

Usage

# full report for one sample
gokdogan sample.exe

# scan a directory, one summary line per file
gokdogan C:\samples --quiet

# JSON for pipelines (SOAR, sandbox pre-filter, …)
gokdogan sample.exe --json report.json

# self-contained HTML report to attach to a case (verdict rationale embedded)
gokdogan sample.exe --html report.html

# MITRE ATT&CK Navigator layer — load it at
# https://mitre-attack.github.io/attack-navigator/ to see the sample's
# techniques highlighted on the matrix, shaded by triage confidence
gokdogan sample.exe --attack-layer sample.attack.json

# fuzzy-compare a sample against a known reference (clustering)
gokdogan suspect.exe --compare known_stealer.exe

# batch-triage a whole dropzone into one sortable table
gokdogan C:\dropzone --csv triage.csv
gokdogan C:\dropzone --jsonl triage.jsonl     # one JSON object per line, SIEM-ready

# cluster a dropzone into families, or diff against a known-good binary
gokdogan C:\dropzone --cluster
gokdogan suspect_svchost.exe --baseline C:\Windows\System32\svchost.exe

# share findings as a MISP event
gokdogan sample.exe --misp sample.misp.json

# your own rule set
gokdogan sample.exe --rules C:\rules\team-rules

# tuning / skips
gokdogan sample.exe --min-strlen 8   # longer minimum string length (default 6)
gokdogan sample.exe --no-yara        # skip the YARA stage
gokdogan sample.exe --no-verify-sig  # skip Authenticode verification (Windows-only)

# opt-in reputation: sends ONLY the SHA-256 (never the file) to VT/MalwareBazaar
gokdogan sample.exe --reputation --vt-key $VT_API_KEY

Reputation lookup is the only feature that touches the network, and it is off unless you pass --reputation with an API key (--vt-key/--mb-key or VT_API_KEY/MB_API_KEY). It sends the sample's SHA-256 only — never the file — and prints a heads-up before any hash leaves the host. The core triage() engine is always fully offline.

In batch mode gokdogan prints one line per sample plus a final tally (N file(s): X high-risk, Y suspicious, Z clean) and writes a flat summary row per file — verdict, score, imphash/rich_hash/ssdeep (for clustering), capabilities, ATT&CK techniques, YARA hits, and counts of embedded PEs / encoded strings / config blobs / anomalies. Sort the CSV by score to work a dropzone worst-first, or group by imphash/rich_hash to cluster variants.

Exit codes are pipeline-friendly: 0 clean, 2 suspicious, 3 high risk — so gokdogan dropzone/ --quiet && echo OK works as a gate.

Sample output

gokdogan triage report — invoice_scan.exe

── File ──────────────────────────────────────────────────
  type       : PE32 executable (GUI) x86
  imphash    : 09d0478591d4f788cb3e5ea416c25237
  rich_hash  : 1e77c08b15cd344c938cc0b7389bbd3b
  ssdeep     : 6144:wYXtmo124T7G/baHXOgAcIXl0FIu0CH+h0FuiiCwSQ5gf:NXtmk2IG/GHAR0FIu7FQ5G
  compiled   : 2031-01-04 11:20:41 UTC  [compile timestamp is in the future]
  signed     : no

── Packer ────────────────────────────────────────────────
  DETECTED: UPX
    - section name 'UPX0' is a known UPX artifact
    - executable section 'UPX1' has entropy 7.91 (>= 7.2)

── Capabilities ──────────────────────────────────────────
  [!!!] process-injection      Writes and executes code in other processes  (T1055)
        CreateRemoteThread, VirtualAllocEx, WriteProcessMemory
  [!!!] keylogging             Captures keystrokes  (T1056.001)
        GetAsyncKeyState, SetWindowsHookExW

── MITRE ATT&CK ──────────────────────────────────────────
  Defense Evasion
    T1055       Process Injection
                from: process-injection, yara:Injection_API_Cluster
  Collection
    T1056.001   Input Capture: Keylogging
                from: keylogging
  Impact
    T1490       Inhibit System Recovery
                from: anti-recovery, yara:Shadow_Copy_Deletion

── Verdict ───────────────────────────────────────────────
  +15  packer detected: UPX
  +18  capability: process-injection
  +18  capability: keylogging
   +5  compile timestamp is in the future
  ...
  HIGH RISK  (score 74, thresholds: suspicious ≥ 30, high risk ≥ 60)

Project layout

gokdogan/
├── gokdogan/
│   ├── engine.py         # orchestrator: triage() pipeline
│   ├── loader.py         # PE parsing, hashes, imphash, anomalies
│   ├── rich.py          # Rich header hash, @comp.id decode, checksum check
│   ├── resources.py      # .rsrc walker: embedded PEs, high-entropy blobs
│   ├── fuzzy.py          # ssdeep + optional TLSH fuzzy hashing / compare
│   ├── entropy.py        # Shannon entropy + thresholds
│   ├── packers.py        # known-section-name table + heuristics
│   ├── strings_ext.py    # ASCII/UTF-16LE extraction + classification
│   ├── decoded.py        # FLOSS-lite: XOR/ADD/ROL/Base64/hex string recovery
│   ├── blobs.py          # config-blob spotting: entropy islands in .data
│   ├── exports.py        # export table + launch-mechanism export detection
│   ├── capabilities.py   # API → behavior rule table (capa-style)
│   ├── attack.py         # capability/YARA → MITRE ATT&CK technique mapping
│   ├── yara_scan.py      # optional yara-python integration
│   ├── verdict.py        # weighted scoring, thresholds
│   ├── models.py         # dataclasses shared by all stages
│   ├── report.py         # ANSI console + JSON renderers
│   ├── html_report.py    # self-contained HTML report (escaped, theme-aware)
│   ├── reputation.py     # opt-in VirusTotal / MalwareBazaar hash lookup
│   ├── summary.py        # flat per-sample rows for batch CSV/JSONL
│   ├── cli.py            # argparse CLI, exit codes
│   ├── web.py            # optional FastAPI upload-and-triage service
│   └── rules/            # bundled starter YARA rules (packaged with the wheel)
└── tests/                # pytest: unit per module + e2e on notepad.exe

Design notes

• Every stage is a pure function over bytes/pefile.PE → dataclasses. Analyzers don't know about each other or about the output format, so adding a stage (e.g. rich-header hashing) means one module + one line in engine.py.
• Capability rules require minimum distinct API hits — GetTickCount alone never lights up anti-debug; three timing/debug APIs together do. This is the difference between a tag an analyst trusts and alert fatigue.
• The verdict is auditable by construction. The score breakdown is the report; there is no hidden model. YARA rules can inject their own weight via meta.weight, so a team's high-confidence family rules can outvote heuristics.
• Graceful degradation: no yara-python, no rules dir, unparseable imports — each degrades to a note in the report instead of a crash.
• Offline by default. The triage() engine never touches the network; the sample is never executed. The single online feature (reputation) is opt-in, hash-only, and lives in the CLI layer — so the analysis core stays safe to run on an air-gapped malware workstation.

Roadmap

• v0.1 — core engine (this repo)
  • PE parsing, hashes, imphash, section entropy
  • packer detection (known names + heuristics)
  • structural anomaly checks (W+X, TLS callbacks, overlay, timestamps)
  • string extraction (ASCII + UTF-16LE) and IOC classification
  • capa-style capability tagging from the import table
  • MITRE ATT&CK technique mapping (capabilities + YARA meta.attack), grouped by tactic
  • ATT&CK Navigator layer export (--attack-layer), shaded by triage confidence
  • YARA integration with score-weighted rules
  • transparent weighted verdict + ANSI/JSON reports
  • pytest suite incl. e2e against known-benign system binaries
• v0.2 — better clustering
  • TLSH/ssdeep fuzzy hashing + --compare similarity scoring
  • Rich header hash, @comp.id toolchain decode, and checksum-tamper detection
  • resource walker: embedded PEs in .rsrc, high-entropy blobs, dropper tagging
  • export table analysis + delay-load imports merged into capabilities
  • --baseline mode: diff a sample against a known-good reference
• v0.3 — deeper strings
  • single-byte XOR/ADD/ROL encoded-string recovery (FLOSS-lite), key-invariant adjacency search
  • Base64 + hex blob detection and decode (IOCs and embedded PEs)
  • config-blob spotting: entropy islands inside calm writable sections
  • true stack-string recovery (needs lightweight code emulation)
• v0.4 — lab integration
  • batch mode with CSV/JSONL summary for a whole dropzone
  • self-contained HTML report with embedded verdict rationale
  • VirusTotal / MalwareBazaar hash lookup (opt-in, hash-only)
• v0.5 — depth & interoperability
  • Authenticode signature verification (WinVerifyTrust) + certificate details
  • overlay content analysis (embedded archives / PEs)
  • managed (.NET) detection: CLR header, flags, obfuscator fingerprints
  • extra clustering hashes (authentihash, impfuzzy) + --cluster / --baseline
  • MISP event export (--misp) for threat-intel sharing
  • ruff lint + coverage in CI
  • pattern-based stack-string recovery (no emulator dependency)
  • pluggable family config extractors (Discord/Telegram/stager URLs)
  • FastAPI upload-and-triage service; wheel-packaged rules + Dockerfile

Testing

pytest -v

Over 100 tests: unit tests cover each analyzer in isolation with synthetic inputs, while the integration suite runs the full pipeline against real system binaries (notepad.exe, kernel32.dll, mmc.exe) and asserts that stock Microsoft binaries never score HIGH_RISK and never trip the dropper / embedded-config / phantom-string false positives.

License

MIT