entropia - A compiled language for Windows position-independe

项目说明

<di="center">

<picture>
<source media="(prefers-color-scheme: dark)" srcset="assets/logo-dark.svg">
<img src="assets/logo-light.svg" alt="Entropia" width="140" />
</picture>

Entropia

A compiled language for Windows position-independent x86-64 shellcode and Beacon Object Files.

![Docs]()

Documentation &nbsp;·&nbsp;
Project Setup &nbsp;·&nbsp;
CLI Reference &nbsp;·&nbsp;
Releases

</div>

---

A complete BOF in less then 30 lines

That is a complete ps BOF. The use_c line pulls the PROCESSENTRY32
struct and the TH32CS_SNAPPROCESS constant straight from the Windows SDK
header, so you write the snapshot kind by name instead of as a raw 0x2 and
the struct layout matches the Microsoft ABI byte for byte. No IAT to
hand-roll, no relocations to apply yourself. Kernel32.X(...) calls lower
to indirect calls through slots the runtime fills before user code runs.

---

Quick start

For prebuilt binaries: grab them from
GitHub Releases and skip
the cargo build step. You can find full walkthrough including at
docs.entropykit.com/getting-started/installation.

---

Why does this exist

Most red-team artifacts ship through a build pipeline of three or four tools
chained together: a C compiler for the source, a linker, a
position-independence transform like DonutGen or sRDI, plus whatever you
wrote yourself to bolt OPSEC tricks on after the fact. Entropia compresses
that pipeline into a single compiler, while pro a modern high-level
language feeling.

The output is the artifact you actually want, either a position-independent
shellcode blob or a Cobalt Strike Beacon Object File, with no post processing
step. The language is small enough to learn in an afternoon and complete
enough to ship production tooling in. The whole OPSEC stack
ships as compiler flags rather than post-build surgery.

Because the compiler owns the pipeline end to end, e composes. A
hand-written PEB walk in asm { ... }, a [Hook("LIB$Func")] attribute,
a [Stage(Init)] startup hook, and --opsec=all share the same internal
representation and do not fight each other. The artifact you ship is the
artifact the compiler emitted, polymorphed by a per-build random seed so
two consecuti of the same source differ by 67 to 78 percent at
the byte level.

---

Examples

Shellcode (fn main entry)

BOF (fn go entry)

Inline assembly + a real PEB walk

OPSEC pre-flight in one line

---

The OPSEC stack

Every technique below is opt-in via --opsec=<list>. The build seed
(--seed=random is the default) dri randomized choice.

| Flag | What it does | Mode |
|---|---|---|
| poly | Rewrites instructions after codegen. xor to sub, mov MR to RM to lea, test to or to and, NOP-run re-decomposition. | both |
| nop_sled | Pads every function entry with random multi-byte NOPs. Shifts every downstream byte offset so whole-binary fuzzy hashes drift between builds. | both |
| strings_xor | XOR-encrypts .rdata and .data with a per-build random key. Decryptor runs before user code. | shellcode |
| stack_strings | Materialises string constants on the stack rather than in .rdata. Eliminates plaintext strings from the artifact. | both |
| direct_syscalls | Auto-imports a HellsGate-style stub. Every Ntdll.X(...) dispatches via syscall inside our code region. | both |
| indirect_syscalls | Auto-imports an indirect-syscall stub. Every Ntdll.X(...) jumps to a syscall;ret gadget inside ntdll itself. | both |
| hashed_imports | Drops every __imp_LIB$Func external symbol from BOFs. Win32 imports resolve at runtime via PEB walk plus LoadLibraryA plus GetProcAddress. | BOF |

Stack spoofing (Draugr-style synthetic call frames) and operator-selectable
sleep masks are a as explicit use opsec_stack_spoof; and
use opsec_sleep_mask; imports.

> Measured byte-le between two builds with --opsec=all and
> different seeds: 67 to 78 percent. Well past every published fuzzy-hash
> threshold.

---

What's in the box

| Binary | What it does |
|---|---|
| entc | The compiler. Takes .etpy source files, produces .bin shellcode or .x64.o BOFs. |
| bof-runner | Local test harness for BOFs. Applies relocations, fills the Beacon API stubs, calls go(args, len). |
| entc-debug | Debug Adapter Protocol server. Powers VS Code F5 and F9. |
| entc-win32gen | Generates typed C headers from Microsoft's win32metadata. |
| VS Code extension | Syntax highlighting, F5 build-and-run, F9 breakpoints inside inline asm. Located at tools//. |

---

Building from source

Requirements

Rust 1.75 or newer (rustup.rs).

Windows x86-64 for running the produced binaries. The compiler itself builds

and runs on Linux and macOS too, but the output targets Windows.

Build e

Three binaries land under target/release/:

Build a single binary

Install the VS Code extension

Reload VS Code (Command Palette to "De: Reload Window") to pick it up.
Other actions (uninstall, status, vsix) are documented at
docs.entropykit.com/getting-started/installation.

<small>Soon comming to VS Code marketplace</small>

---

Documentation

Reference and guides live at
docs.entropykit.com.

| Section | What it covers |
|---|---|
| Getting Started | Install, project setup, first program, CLI reference, every compiler flag. |
| Language | Types, control flow, structs, pointers, indexing, casts, try and catch, inline asm, intrinsics, garbage collector. |
| Modules and Stdlib | use and use_c, what is in the standard library. |
| Win32 | How Lib.Function(...) calls work end to end. Custom resolvers. |
| BOF Mode | go(args, len), Beacon API, auto-generated Aggressor scripts, local testing, F5 debugging. |
| OPSEC | Every flag explained with examples and trade-offs. |
| Ad | [O(Slot)], [Hook(...)], lifecycle stages. |

A self-contained PDF snapshot of the docs ships with every tagged release.

---

Status

Entropia is pre-1.0 and the surface is still moving. Expect changes between
commits to the compiler internals; the source-le surface is
stable enough that the examples in this README are expected to keep working.

Roughly what is done and what is in flight:

| Area | Status |
|---|---|
| Compiler front end (lexer, parser, type checker) | Stable. |
| Codegen and encoder | Stable. New mnemonics get added as needed. |
| BOF mode | Stable. |
| Shellcode mode | Stable. |
| OPSEC stack (poly, syscalls, sleep masks, hashed imports) | Stable. |
| VS Code F5 / F9 flow | Stable. |
| Garbage collector | Stable. Manual mode is the recommended default for size-sensiti. |
| Linux / macOS toolchain support | Build-only. Generated artifacts always target Windows x86-64. |
| Tests | To be implemented. |
| ARM64 backend | Not started. |

---

Contributing

Issues and pull requests are welcome. A few ground rules:

Bug reports: include the smallest .etpy that reproduces the issue and

the exact entc compile command line. Compiler bugs that fail at build time
are easier to triage than runtime crashes; runtime crashes need the artifact
and the host en too.

New language features: open an issue first to discuss the design. The

language surface is small on purpose.

OPSEC techniques: new --opsec=* flags or new opsec_* stdlib modules

are encouraged. Pair the implementation with a stdlib example and a docs
page explaining the trade-off.

Pre-commit: run cargo build --release and cargo test --release

before pushing. We will add a CI workflow that enforces this.

---

Authorization and responsible use

Entropia is dual-use security tooling. The example BOFs implement
well-documented offensi (process enumeration, token
impersonation, remote injection, LSASS dump, AMSI and ETW silencing) that
you can find in mainstream tradecraft references like nanodump, mimikatz,
TrustedSec's CS-Situational-Awareness-BOF collection, and Cobalt Strike's
stock BOF library.

Use Entropia only in authorized red-team engagements, CTF en, and
security research. The authors assume no liability for misuse.

---

Acknowledgments

Entropia stands on the shoulders of a community of public research:

Cobalt Strike for defining the BOF format and the Beacon API surface.

TrustedSec for the CS-Situational-Awareness-BOF collection and the

COFFLoader reference.

nanodump, freshycalls, HellsGate, HalosGate, TartarusGate

for syscall-stub research.

Ekko, Foliage, Draugr for sleep-mask and stack-spoofing

techniques.

win32metadata for the typed Win32 surface generation.

---

<di="center">

Documentation &nbsp;·&nbsp;
Releases &nbsp;·&nbsp;
EntropyKit

</div>

项目信息

开发语言：C

Star 数：247

技术要点

该项目属于红蓝攻防方向的开源资源，代码结构清晰，适合安全研究人员学习参考。项目围绕A compiled language for Windows position-independent x86-64 shellcode and Beacon Object Files.展开，提供了可运行的实现，对理解相关安全机制、工具原理与攻防技术具有较高的研究价值。

从技术实现角度看，此类项目的核心在于对底层原理的深入理解与工程化落地。开发者在研究过程中可以结合官方文档与社区讨论，梳理项目的初始化流程、核心模块职责与数据流转，逐步掌握其中的技术细节与设计思路。

使用与学习建议

1. 下载源码压缩包，解压到本地环境。

2. 根据项目类型准备对应的运行环境与依赖。

3. 按照 README 中的步骤完成配置与部署。

4. 在隔离的测试环境中运行验证，避免影响生产系统。

免责声明

本资源来源于开源社区，仅供安全研究、技术学习与合法授权范围内的攻防演练使用，请勿用于任何非法或侵害他人权益的用途。使用本项目产生的一切后果由使用者自行承担。