# n1ght-w0lf/hawkeye architecture

> Architecture diagram of the GitHub repository n1ght-w0lf/hawkeye, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/n1ght-w0lf/hawkeye
- Repository: https://github.com/n1ght-w0lf/hawkeye

## Overview

#### 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.

Main entry points: [`report/index.html`](https://github.com/n1ght-w0lf/hawkeye/blob/master/report/index.html) (Report shell), [`HawkEye.py`](https://github.com/n1ght-w0lf/hawkeye/blob/master/HawkEye.py) (HawkEye controller), [`report/js/loader.js`](https://github.com/n1ght-w0lf/hawkeye/blob/master/report/js/loader.js) (Report loader), [`report/output/data.json`](https://github.com/n1ght-w0lf/hawkeye/blob/master/report/output/data.json) (Report dataset)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_analysis["Live Analysis"]
  node_cli["HawkEye controller<br/>Python CLI<br/>[HawkEye.py]"]
  node_target{{"Target process<br/>Windows executable"}}
  node_frida["Frida runtime<br/>instrumentation bridge"]
end

subgraph group_hooks["Frida Hook Agents"]
  node_process_hooks["Process &amp; memory hooks<br/>Frida agent<br/>[process_hooks.js]"]
  node_file_hooks["File-system hooks<br/>Frida agent<br/>[file_hooks.js]"]
  node_registry_hooks["Registry hooks<br/>Frida agent<br/>[registry_hooks.js]"]
  node_internet_hooks["Internet &amp; DNS hooks<br/>Frida agent<br/>[internet_hooks.js]"]
  node_general_hooks["DLL, API &amp; mutex hooks<br/>Frida agent<br/>[general_hooks.js]"]
end

subgraph group_report["Static Report"]
  node_dataset[("Report dataset<br/>JSON contract<br/>[data.json]")]
  node_report_html["Report shell<br/>HTML application<br/>[index.html]"]
  node_loader["Report loader<br/>browser JavaScript<br/>[loader.js]"]
  node_styles["Report styles<br/>CSS<br/>[style.css]"]
  node_graph_libs["Visualization libraries<br/>vendored frontend libraries"]
  node_assets["Report assets<br/>images"]
  node_browser(("Local browser<br/>report viewer"))
end

node_cli -->|"controls"| node_frida
node_cli -->|"spawns or attaches"| node_target
node_frida -->|"injects agents"| node_target
node_process_hooks -->|"emits events"| node_frida
node_file_hooks -->|"emits events"| node_frida
node_registry_hooks -->|"emits events"| node_frida
node_internet_hooks -->|"emits events"| node_frida
node_general_hooks -->|"emits events"| node_frida
node_frida -->|"message callback"| node_cli
node_cli -->|"writes events"| node_dataset
node_browser -->|"opens"| node_report_html
node_report_html -->|"loads"| node_loader
node_report_html -->|"applies"| node_styles
node_report_html -->|"uses"| node_graph_libs
node_report_html -->|"displays"| node_assets
node_loader -->|"fetches"| node_dataset

click node_cli "https://github.com/n1ght-w0lf/hawkeye/blob/master/HawkEye.py"
click node_process_hooks "https://github.com/n1ght-w0lf/hawkeye/blob/master/hooks/process_hooks.js"
click node_file_hooks "https://github.com/n1ght-w0lf/hawkeye/blob/master/hooks/file_hooks.js"
click node_registry_hooks "https://github.com/n1ght-w0lf/hawkeye/blob/master/hooks/registry_hooks.js"
click node_internet_hooks "https://github.com/n1ght-w0lf/hawkeye/blob/master/hooks/internet_hooks.js"
click node_general_hooks "https://github.com/n1ght-w0lf/hawkeye/blob/master/hooks/general_hooks.js"
click node_dataset "https://github.com/n1ght-w0lf/hawkeye/blob/master/report/output/data.json"
click node_report_html "https://github.com/n1ght-w0lf/hawkeye/blob/master/report/index.html"
click node_loader "https://github.com/n1ght-w0lf/hawkeye/blob/master/report/js/loader.js"
click node_styles "https://github.com/n1ght-w0lf/hawkeye/blob/master/report/css/style.css"
click node_graph_libs "https://github.com/n1ght-w0lf/hawkeye/tree/master/report/libs"
click node_assets "https://github.com/n1ght-w0lf/hawkeye/tree/master/report/images"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_target,node_frida toneBlue
class node_process_hooks,node_file_hooks,node_registry_hooks,node_internet_hooks,node_general_hooks toneAmber
class node_dataset,node_report_html,node_loader,node_styles,node_graph_libs,node_assets,node_browser toneMint
```

## Components

### Live Analysis

Privileged Windows malware instrumentation.

- [HawkEye controller](https://github.com/n1ght-w0lf/hawkeye/blob/master/HawkEye.py): Python CLI · Selects spawn or attach, manages Frida, collects events, and exports report data. · `HawkEye.py`
- **Target process**: Windows executable · Spawned executable or process selected by PID.
- **Frida runtime**: instrumentation bridge · Injects JavaScript agents and carries messages to Python.

### Frida Hook Agents

Extensible API-monitoring payloads injected into the target.

- [Process & memory hooks](https://github.com/n1ght-w0lf/hawkeye/blob/master/hooks/process_hooks.js): Frida agent · `hooks/process_hooks.js`
- [File-system hooks](https://github.com/n1ght-w0lf/hawkeye/blob/master/hooks/file_hooks.js): Frida agent · `hooks/file_hooks.js`
- [Registry hooks](https://github.com/n1ght-w0lf/hawkeye/blob/master/hooks/registry_hooks.js): Frida agent · `hooks/registry_hooks.js`
- [Internet & DNS hooks](https://github.com/n1ght-w0lf/hawkeye/blob/master/hooks/internet_hooks.js): Frida agent · `hooks/internet_hooks.js`
- [DLL, API & mutex hooks](https://github.com/n1ght-w0lf/hawkeye/blob/master/hooks/general_hooks.js): Frida agent · `hooks/general_hooks.js`

### Static Report

Passive local browser visualization.

- [Report dataset](https://github.com/n1ght-w0lf/hawkeye/blob/master/report/output/data.json): JSON contract · Compatibility boundary between event collection and static UI. · `report/output/data.json`
- [Report shell](https://github.com/n1ght-w0lf/hawkeye/blob/master/report/index.html): HTML application · `report/index.html`
- [Report loader](https://github.com/n1ght-w0lf/hawkeye/blob/master/report/js/loader.js): browser JavaScript · Loads and renders collected activity data. · `report/js/loader.js`
- [Report styles](https://github.com/n1ght-w0lf/hawkeye/blob/master/report/css/style.css): CSS · `report/css/style.css`
- [Visualization libraries](https://github.com/n1ght-w0lf/hawkeye/tree/master/report/libs): vendored frontend libraries · Bootstrap, jQuery, D3, Dagre-D3, and Panzoom support the report UI. · `report/libs`
- [Report assets](https://github.com/n1ght-w0lf/hawkeye/tree/master/report/images): images · `report/images`
- **Local browser**: report viewer · Consumes exported JSON without a report server.

## Connections

- HawkEye controller → Frida runtime: controls
- HawkEye controller → Target process: spawns or attaches
- Frida runtime → Target process: injects agents
- Process & memory hooks → Frida runtime: emits events
- File-system hooks → Frida runtime: emits events
- Registry hooks → Frida runtime: emits events
- Internet & DNS hooks → Frida runtime: emits events
- DLL, API & mutex hooks → Frida runtime: emits events
- Frida runtime → HawkEye controller: message callback
- HawkEye controller → Report dataset: writes events
- Local browser → Report shell: opens
- Report shell → Report loader: loads
- Report shell → Report styles: applies
- Report shell → Visualization libraries: uses
- Report shell → Report assets: displays
- Report loader → Report dataset: fetches