n1ght-w0lf/hawkeye

Purpose and Entry Points

HawkEye is a Windows malware dynamic-instrumentation utility built on Frida. It either spawns a supplied executable or attaches to an existing PID, injects JavaScript hooks, collects runtime activity, and renders it as a local HTML report. The CLI entry point is HawkEye.py.

Controller and Analysis Lifecycle

HawkEye.py is the orchestration boundary: it accepts --path or --pid, selects spawn versus attach behavior, manages Frida instrumentation, receives hook events, and writes report data. It depends on the host Python runtime plus frida and psutil; analysis must run in an isolated Windows environment because the target executes normally.

Frida Hook Payloads

Instrumentation is divided by observable behavior, with JavaScript agents loaded into the target process:

• Process and memory activity: hooks/process_hooks.js

• File-system operations: hooks/file_hooks.js

• Registry access and mutation: hooks/registry_hooks.js

• Internet/DNS activity: hooks/internet_hooks.js

• DLL/API resolution and mutex behavior: hooks/general_hooks.js

These scripts hook common Windows APIs and emit structured events back across Frida’s Python/JavaScript message boundary.

Event Collection and Persistence

The central control flow is target process → injected hook script → Frida message callback in HawkEye.py → report dataset. The persisted handoff to the UI is report/output/data.json, allowing the report viewer to remain a static client-side artifact rather than requiring a report server.

Report Application

The rendered report is rooted at report/index.html; behavior and data loading are implemented in report/js/loader.js. It consumes report/output/data.json to present collected malware actions, likely including relationship/flow visualization supported by bundled graph libraries.

Visualization and Static Dependencies

The report is a local browser application with styling in report/css/style.css. Its material frontend dependencies are vendored under report/libs, notably Bootstrap for layout, jQuery for DOM support, D3 and Dagre-D3 for graph rendering, and Panzoom for graph navigation. Report branding/assets reside in report/images.

Architectural Boundaries

The design separates privileged live analysis from passive visualization: Frida and Python interact with the running malware process, while the browser consumes only exported JSON. Hook-category scripts form the extensibility boundary for additional monitored APIs; the report data schema between HawkEye.py, report/output/data.json, and report/js/loader.js is the key compatibility contract.