petriage 0.4.1

Cross-platform PE file surface analysis tool for malware analysts
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110

<p align="center">
  <img src="images/PETriage.png" alt="PETriage" width="600">
</p>

# PETriage

[![Crates.io](https://img.shields.io/crates/v/petriage.svg)](https://crates.io/crates/petriage)
[![Docs.rs](https://docs.rs/petriage/badge.svg)](https://docs.rs/petriage)
[![License](https://img.shields.io/crates/l/petriage.svg)](https://github.com/uky007/PETriage)
[![GitHub tag](https://img.shields.io/github/v/tag/uky007/PETriage)](https://github.com/uky007/PETriage/tags)

A fast, cross-platform PE (Portable Executable) surface analysis tool for malware triage, written in Rust.
Designed for analysts who need practical PE triage on Linux, macOS, and Windows without relying on a Windows-only workflow.

Formerly `readpe` (renamed to avoid naming collisions with existing tools).

## Concept

- **Static-only** -- The PE is never loaded or executed. Safe for malware triage.
- **CLI-first** -- Lightweight default workflow suitable for batch analysis and automation.
- **Composable** -- JSON/NDJSON output for piping to `jq`, SIEMs, and scripting pipelines.
- **Offline** -- No network calls. Suitable for fully air-gapped environments.

## Interfaces

| Interface | Build | Description |
|-----------|-------|-------------|
| **CLI** | `cargo build --release` | Default workflow for PE triage, structured output, anomaly detection, and batch automation. |
| **TUI** | `cargo build --release --features tui` | Interactive hex viewer with PE region navigation. |
| **GUI** | `cargo build --release --features gui` | Tabbed analysis, drag & drop, import/string filters, entropy color-coding, PE header editor. |

## Quick Install

Default CLI build:

```
cargo install petriage
```

For TUI and GUI builds, build from source with feature flags.

Or build from source:

```
git clone https://github.com/uky007/petriage.git
cd petriage
cargo build --release
```

See [docs/installation.md](docs/installation.md) for GUI/TUI build dependencies and cross-compilation.

## Quick Usage

```
petriage <file.exe>              # Surface analysis (all except strings)
petriage <file.exe> -a           # All information including strings
petriage <file.exe> -H           # Headers only
petriage <file.exe> -i           # Imports only
petriage <file.exe> --hashes     # File hashes only
petriage <file.exe> --json       # JSON output
petriage --batch <dir> --ndjson  # Batch-analyze all PEs in a directory
petriage <file.exe> --fail-on warning  # Exit code 3 if anomalies meet the selected threshold
```

```
petriage -x <file.exe>           # TUI hex viewer
petriage-gui                     # GUI (file dialog)
petriage-gui <file.exe>          # GUI (open file directly)
```

See [docs/usage.md](docs/usage.md) for full CLI options, `jq` recipes, TUI/GUI details, and example output.

## Screenshots

### CLI

![PETriage CLI](images/petriage_cui_v0.1.0.png)

### GUI

![PETriage GUI](images/petriage_gui_v0.1.0.png)

### Headers (Structure View + Editor)

![PETriage Headers](images/petriage_gui_headers_v0.4.1.png)

### Header Editor (Inline Editing)

![PETriage Editor](images/petriage_gui_editor_v0.4.1.png)

## Exit Codes

| Code | Meaning |
|------|---------|
| 0 | Success |
| 1 | Input error (file not found, read failure, invalid PE) |
| 2 | Output error (file write failure) |
| 3 | Anomaly threshold exceeded (`--fail-on`) |

## Docs

- [Overview & Features](https://github.com/uky007/PETriage/blob/main/docs/description.md)
- [Installation](https://github.com/uky007/PETriage/blob/main/docs/installation.md)
- [Usage & Examples](https://github.com/uky007/PETriage/blob/main/docs/usage.md)
- [Survey of Existing Tools](https://github.com/uky007/PETriage/blob/main/docs/survey.md)
- [Future Work](https://github.com/uky007/PETriage/blob/main/docs/future_work.md)

## License

MIT OR Apache-2.0