https://github.com/k4ryuu/sigscan-ts
Ultra-fast TypeScript binary signature scanner for Node.js and Bun
https://github.com/k4ryuu/sigscan-ts
binary-analysis binary-signature bun cheat-engine gamedata ida-pattern nodejs pattern-scanner reverse-engineering sigscan typescript x64dbg
Last synced: 17 days ago
JSON representation
Ultra-fast TypeScript binary signature scanner for Node.js and Bun
- Host: GitHub
- URL: https://github.com/k4ryuu/sigscan-ts
- Owner: K4ryuu
- License: mit
- Created: 2026-05-28T12:52:45.000Z (23 days ago)
- Default Branch: main
- Last Pushed: 2026-05-29T21:01:23.000Z (22 days ago)
- Last Synced: 2026-05-29T21:05:33.940Z (22 days ago)
- Topics: binary-analysis, binary-signature, bun, cheat-engine, gamedata, ida-pattern, nodejs, pattern-scanner, reverse-engineering, sigscan, typescript, x64dbg
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/sigscan-ts
- Size: 832 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
sigscan-ts
High-performance binary signature scanner and gamedata verifier
Zero runtime dependencies • Hybrid Buffer.indexOf prefix optimization • Fully Type-Safe • Auto relocatable signatures
Get Started »
·
View Examples
## About The Project
Hey! I built this because I was working on a few game server modding tools and got tired of copy-pasting raw C++ signature scanning algorithms or relying on slow, outdated JavaScript libraries.
This is a modern, high-performance binary signature scanner. It runs on Node.js and Bun with no runtime dependencies whatsoever.
## Why this package is special
- **Zero runtime dependencies** - All dependencies are strictly for development and compilation. Check the `package.json` for yourself.
- **Hybrid search engine** - Rather than scanning byte-by-byte, it parses your signature to find the longest continuous prefix, performs a native C++ `indexOf` search, and then verifies wildcards around candidates. See the benchmark table below.
- **Extremely forgiving parser** - Copy signatures directly from Cheat Engine, IDA Pro, x64dbg, or C-style arrays (`{ 0x48, 0x8b, 0xc4, ?? }`). It handles spaces, dots, commas, raw hex strings, and escaped sequences out of the box.
- **Built-in CLI & Gamedata Verifier** - Scan single signatures or batch-verify entire `gamedata.json` files (supporting both CounterStrikeSharp and SwiftlyS2 formats) against server binaries in seconds.
## Performance
Benchmarked on a 100 MB random buffer with 3 planted signatures (Apple M2 Pro, Bun 1.3).
| Pattern type | Example | Time | vs naive loop |
|---|---|---|---|
| No wildcards | `DE AD BE EF CA FE BA BE` | ~8.5 ms | **~15x faster** |
| Wildcards (prefix-opt) | `DE AD ?? EF CA ?? BA BE` | ~9.4 ms | **~13x faster** |
| Fragmented wildcards | `?? AD ?? EF ?? FE ?? BE` | ~12.7 ms | **~10x faster** |
| `scan()` with `fast: true` | any | ~4.3 ms | **~30x faster** |
| Naive JS loop (baseline) | — | ~128 ms | 1x |
Run it yourself: `bun run bench`
## Installation
```bash
npm install sigscan-ts
pnpm add sigscan-ts
bun add sigscan-ts
```
## Quick example
Here is a quick example of a one-off pattern scan:
```typescript
import { readFileSync } from "fs";
import { scan, PatternScanner } from "sigscan-ts";
const buffer = readFileSync("libserver.so");
// 1. One-off quick scan
const result = scan(buffer, "48 8B C4 ? 53 ?? 90");
if (result.found) {
console.log(`Found pattern at ${result.offsets.length} locations.`);
console.log(`Primary offset: 0x${result.offsets[0].toString(16)}`);
console.log(`Is the signature unique/reliable? ${result.reliable}`);
}
// 2. Reusable scanner (efficient for scanning multiple signatures)
const scanner = new PatternScanner(buffer);
const offsets = scanner.findPattern("55 48 89 E5");
console.log("Offsets found:", offsets);
```
## Multi-pattern scan
Scan many named signatures in one call — useful for gamedata.json verification or any batch scan:
```typescript
import { readFileSync } from "fs";
import { PatternScanner } from "sigscan-ts";
const buffer = readFileSync("server.so");
const scanner = new PatternScanner(buffer);
// returns Record
const offsets = scanner.findPatterns({
UTIL_ClientPrintAll: "55 48 89 E5 41 57 4D 89 CF",
GiveNamedItem: "55 48 89 E5 41 57 41 56 41 55",
CCSPlayer_Respawn: "48 8B 05 ?? ?? ?? ?? 48 85",
});
// returns Record
const results = scanner.scanPatterns({
UTIL_ClientPrintAll: "55 48 89 E5 41 57 4D 89 CF",
GiveNamedItem: "55 48 89 E5 41 57 41 56 41 55",
});
if (results["GiveNamedItem"].reliable) {
console.log("unique match at", results["GiveNamedItem"].offsets[0].toString(16));
}
```
Standalone helpers also available: `findPatterns(buffer, patterns)` and `scanPatterns(buffer, patterns)`.
## Command Line Interface (CLI)
If you install the package globally or run it via npx, you can use the built-in CLI:
```bash
# Scan a binary for a specific signature
sigscan-ts -b libserver.so -p "48 8B C4 ?? 53"
# Fast pattern scan that stops after proving a second match
sigscan-ts -b libserver.so -p "48 8B C4 ?? 53" --fast
# Verify an entire gamedata.json file against binaries
# (Supports folder paths or passing multiple files via multiple -b flags.
# Platform types and libraries are automatically detected!)
sigscan-ts -b /path/to/binaries_dir -g latest-gamedata.json
sigscan-ts -b libserver.so -b server.dll -g latest-gamedata.json
```
Here is a preview of the batch-verification mode running on both Windows and Linux binaries side-by-side:
## Supported Pattern Formats
The parser automatically detects and handles almost any copy-pasted pattern style:
- **IDA Pro**: `"48 8B C4 ?? 53 ? 90"`
- **x64dbg**: `"48.8B.C4.??.53"` (Dot-separated)
- **Cheat Engine**: `"48 8b c4 ?? 53"`
- **C-style Array**: `"{ 0x48, 0x8b, 0xc4, ??, 0x53 }"`
- **Escaped Hex**: `"\x48 \x8B \xC4 ?? \x53"`
- **Raw Hex String**: `"488bc4??53"`
## For developers
If you want to contribute or build the library locally, please check out the [contributing guide](CONTRIBUTING.md).
## License
MIT - do whatever you want with it
---
## Credits
Built by [K4ryuu](https://github.com/K4ryuu)