Secrux Ghost Bits — Specialized Scanner

中文版本 / Chinese: see README.zh.md

A standalone specialized scanner for the Ghost Bits / Cast Attack vulnerability family in Java codebases, based on the Black Hat Asia 2026 talk "Cast Attack — A New Threat Posed by Ghost Bits in Java" (浅蓝 B1u3r / 1ue, contributor: SpringKill). Part of the Secrux family but does not depend on the Secrux platform — runs standalone on a developer laptop or in CI.

Two responsibilities:

1. Source-code sink detection (15 rules GB-001 … GB-015) using tree-sitter-java AST + context-aware filters.
2. Vulnerable-dependency lookup against pom.xml / build.gradle / build.gradle.kts for libraries known to ship Ghost Bits sinks (Angus Mail, Jetty, Spring Boot, Apache HttpClient, fastjson, Tomcat, …).

Outputs: rich-coloured terminal, Markdown, self-contained HTML — all bilingual (English & Chinese). Default is English; --lang zh switches to Chinese; --lang both produces two reports for cross-language teams.

---

🛡️ Part of the Secrux Family

Secrux Ghost Bits is the open-source specialist edition focused exclusively on the Ghost Bits / Cast Attack class — released under Apache 2.0. Its enterprise sibling Secrux is a commercial security governance platform (self-hostable, multi-tenant) — and ships a built-in "Ghost Bits 专项 audit" workflow as part of its LLM-assisted code audit / vulnerability mining feature.

Both editions detect the same attack class but hit different points on the cost / depth tradeoff curve:

• Ghost Bits (this repo) — fast static specialist scanner. Runs in seconds, no API key, no infrastructure, no LLM credits.
• Secrux Ghost Bits 专项 — LLM-driven deep code inspection engine. Surfaces sinks the static scanner cannot reach, with full audit reasoning and IDE-inline review — needs a Secrux deployment and LLM budget.

Both editions are maintained separately — this isn't lite-vs-pro, it's "fast & free" vs "deep & AI-assisted".

Comparison

	Ghost Bits (this repo)	Secrux Ghost Bits 专项 (platform)
Engine	Static specialist scanner	LLM-driven deep code inspection
Form factor	Single binary / pip install	Self-hosted Docker / Kubernetes
Multi-tenant	No (one shot, one repo)	Yes
IDE integration	—	IntelliJ plugin with inline findings
Output	terminal / Markdown / HTML / JSON	Web console + IDE inline + full audit report + SARIF
Cost	Free, no API key	Requires LLM credits + platform infrastructure
License	Apache 2.0 (open source)	Commercial
Best for	Quick standalone scan, CI gate, dev laptop	LLM-assisted deep code audit, cross-codebase reasoning, organization-wide governance

When to use which

• ✅ Ghost Bits — quick专项 audit on one Java repo, CI gate, dev laptop, no infrastructure or API budget.
• ✅ Secrux Ghost Bits 专项 — LLM-assisted code audit / vulnerability mining for cross-codebase reasoning, IDE-inline review, multi-team governance.
• ✅ Both together — run Ghost Bits for a fast first pass; feed the codebase into Secrux for the deeper LLM-assisted audit.

Side-by-side preview

Secrux platform — full-featured commercial dashboard:

Main Dashboard	Vulnerability Management	Ghost Bits Audit

Secrux Ghost Bits (this open-source tool) — terminal CLI and a local web service:

Terminal CLI	Local Web Service

Get the platform

Secrux is a commercial product (closed source). For evaluation, pricing, or deployment, contact the Secrux team.

Note: The community-edition Ghost Bits scanner you are looking at right now is the only open-source piece of the family — Apache 2.0, no strings attached. The full Secrux platform requires a commercial license.

---

What is Ghost Bits?

Java's char is 16-bit. Operations like (byte) ch, ch & 0xff, OutputStream.write(int), DataOutputStream.writeBytes(String) silently keep only the low 8 bits. An attacker-controlled 阮 (U+962E) becomes . (0x2E), 丰 (U+4E30) becomes 0 (0x30), č becomes \r — bypassing string-level WAFs and producing structural ASCII characters in the byte stream. Downstream impact:

• WAF / SQL-injection bypass (Jackson charToHex, fastjson \u/\x)
• SMTP injection / email hijacking (CVE-2025-7962, Angus Mail; affects Jira / Confluence / Bitbucket / TeamCity / Liferay / Keycloak supply chain)
• Path traversal (CVE-2023-32315 Openfire, CVE-2025-41242 Spring; Jetty TypeUtil.convertHexDigit)
• HTTP request smuggling / CRLF (Apache HttpClient ≤4.5.9 ByteArrayBuffer)
• Response-header XSS (CVE-2026-21933 JDK HttpServer)
• File-upload extension bypass (Tomcat RFC2231Utility: 1.阶sp → 1.jsp)
• Base64 decoder bypass (sun.misc.BASE64Decoder and friends)

---

Install

Option A: Pre-built single-file binary (recommended; no Python required)

Download from Releases:

Platform	File
Linux x86_64	secrux-ghost-bits-linux-x64
Linux ARM64	secrux-ghost-bits-linux-arm64
macOS Apple Silicon	secrux-ghost-bits-macos-arm64
Windows x86_64	secrux-ghost-bits-windows-x64.exe

chmod +x secrux-ghost-bits-linux-x64
./secrux-ghost-bits-linux-x64 scan ./your-java-project

Verify with the published SHA-256 checksums:

sha256sum -c SHA256SUMS.txt

Option B: pip install directly from GitHub

Requires Python ≥ 3.10:

pip install git+https://github.com/springkill/secrux-ghost-bits.git
# or, isolated:
pipx install git+https://github.com/springkill/secrux-ghost-bits.git

Option C: download wheel from a release

pip install secrux_ghost_bits-0.1.0-py3-none-any.whl

Option D: from source

git clone https://github.com/springkill/secrux-ghost-bits.git
cd secrux-ghost-bits
python3 -m venv .venv && source .venv/bin/activate
pip install -e .

Either way, the secrux-ghost-bits command becomes available.

Usage

# Scan a project (default: English terminal output)
secrux-ghost-bits scan /path/to/your/java/project

# Chinese
secrux-ghost-bits scan ./project --lang zh

# Bilingual output (produces report.en.md / report.zh.md / report.en.html / report.zh.html)
secrux-ghost-bits scan ./project --format md --format html --out report.md --lang both

# Run only specific rules
secrux-ghost-bits scan ./project --rule GB-005 --rule GB-009

# Include test code (suppressed by default)
secrux-ghost-bits scan ./project --include-tests

# Skip dependency or source scanning
secrux-ghost-bits scan ./project --no-deps
secrux-ghost-bits scan ./project --no-source

# Dump structured JSON
secrux-ghost-bits scan ./project --json findings.json

# List all rules (Chinese / English)
secrux-ghost-bits list-rules --lang zh
secrux-ghost-bits list-rules --lang en

Local web service

Prefer a browser? Spin up a local web service and scan via the GUI:

secrux-ghost-bits serve            # http://127.0.0.1:8765/
secrux-ghost-bits serve --port 9000 --lang zh

The browser UI lets you:

• Upload a .zip / .tar.gz archive of a Java project, or point at a local path
• Toggle severity filter, include test code, or skip dependency check
• View findings inline with code snippets, severity badges, and fix suggestions
• Switch language between English and Chinese on the fly
• Hit /api/scan for a JSON response if you want to integrate with other tools

By default the server binds to 127.0.0.1 only. Use --host 0.0.0.0 to expose it on a trusted network — be careful about who can reach the upload endpoint.

Exit codes:

code	meaning
0	no HIGH findings
1	at least one HIGH source finding
2	dependency findings only (no HIGH source)

These map naturally onto CI gates.

---

Rules

Rule	What it catches
GB-001	Explicit (byte) cast on a char-typed expression
GB-002	bytes[i] = (byte) chars[i] bulk truncation in a loop
GB-003	ch & 0xff / ch & 255 masking
GB-004	OutputStream.write(int) / ByteArrayOutputStream.write(int) with a char arg
GB-005	DataOutputStream#writeBytes(String)
GB-006	RandomAccessFile#writeBytes(String)
GB-007	Deprecated 4-arg String#getBytes(int, int, byte[], int)
GB-008	java.io.StringBufferInputStream (deprecated)
GB-009	Custom hex decoder folding non-hex characters (convertHexDigit-style pattern)
GB-010	Integer.parseInt(charSeq, radix) in escape-sequence decoders (\u/\x lexer pattern)
GB-011	lookupTable[c & 0xff] / [(byte) c] Base64-style indexing
GB-012	RFC2231-style out.write((byte) c) else-branch (file-upload encoding bypass)
GB-013	Char-to-byte truncation in SMTP / mail-protocol code paths (CVE-2025-7962 family)
GB-014	Char-to-byte truncation in HTTP header buffer code paths (request-smuggling family)
GB-015	Method named decode/url/uri/path writes (byte) c — review for path bypass

Filters (false-positive reduction)

• range_guard — when the enclosing method already validates the value range (if (c < 0x80), Character.isAscii(c), if (c > 0x7F) throw, …), the finding is downgraded to INFO so the line still appears in the report for review.
• literal_source — when the cast operand or OutputStream.write(...) argument is a hard-coded char or integer literal, the finding is suppressed.
• test_path — Maven / Gradle test layouts (/src/test/, /src/it/, *Test.java, *IT.java, …) are suppressed by default; pass --include-tests to include them. Matching is anchored to the standard test layout.

---

Dependency catalog

Alongside source-code scanning, the tool inspects pom.xml / build.gradle / build.gradle.kts and flags dependencies that ship known Ghost Bits / Cast Attack sinks — covering Angus Mail, Jetty, Spring Boot, Apache HttpClient, fastjson, Tomcat, and more. Each finding carries a bilingual security note and the relevant CVE references.

The catalog is configurable: extend it with internal coordinates or refine version cutoffs to fit your environment.

---

License

Apache License 2.0. Full text in LICENSE; attribution and third-party credits in NOTICE.