Initial skeleton: README, CVE inventory, roadmap, ARCH, ethics + copy_fail_family module absorbed from DIRTYFAIL
This commit is contained in:
@@ -0,0 +1,119 @@
|
||||
# Architecture
|
||||
|
||||
## Module model
|
||||
|
||||
Each CVE (or tightly-related family of CVEs sharing a primitive) is
|
||||
a **module** under `modules/`. A module is a self-contained
|
||||
exploit + detection + metadata bundle that exports a standard
|
||||
interface to the top-level dispatcher.
|
||||
|
||||
### Module layout
|
||||
|
||||
```
|
||||
modules/<module_name>/
|
||||
├── MODULE.md # Human-readable writeup of the bug
|
||||
├── NOTICE.md # Credits to original researcher
|
||||
├── kernel-range.json # Machine-readable affected kernels
|
||||
├── module.c # Implements iamroot_module interface
|
||||
├── module.h
|
||||
├── detect/
|
||||
│ ├── auditd.rules # blue team detection
|
||||
│ ├── sigma.yml
|
||||
│ └── yara.yara
|
||||
├── src/ # exploit internals
|
||||
└── tests/ # per-module tests (run in CI matrix)
|
||||
```
|
||||
|
||||
### `iamroot_module` interface (planned, Phase 1)
|
||||
|
||||
```c
|
||||
struct iamroot_module {
|
||||
const char *name; /* "copy_fail" */
|
||||
const char *cve; /* "CVE-2026-31431" */
|
||||
const char *summary; /* one-line description */
|
||||
|
||||
/* Return 1 if host appears vulnerable, 0 if patched/immune,
|
||||
* -1 if probe couldn't run. May call entrybleed_leak_kbase()
|
||||
* etc. from core/ if a leak primitive is needed. */
|
||||
int (*detect)(struct iamroot_host *host);
|
||||
|
||||
/* Run the exploit. Caller has already passed the
|
||||
* authorization gate. Returns 0 on root acquired,
|
||||
* nonzero on failure. */
|
||||
int (*exploit)(struct iamroot_host *host, struct iamroot_opts *opts);
|
||||
|
||||
/* Apply a runtime mitigation for this CVE (sysctl, module
|
||||
* blacklist, etc.). Returns 0 on success. NULL if no
|
||||
* mitigation is offered. */
|
||||
int (*mitigate)(struct iamroot_host *host);
|
||||
|
||||
/* Undo --exploit-backdoor or --mitigate side effects. */
|
||||
int (*cleanup)(struct iamroot_host *host);
|
||||
|
||||
/* Affected kernel version range, distros covered, etc. */
|
||||
const struct iamroot_kernel_range *ranges;
|
||||
size_t n_ranges;
|
||||
};
|
||||
```
|
||||
|
||||
Modules register themselves at link time via a constructor-attribute
|
||||
table. The top-level `iamroot` binary iterates the registry on each
|
||||
invocation.
|
||||
|
||||
## Shared `core/`
|
||||
|
||||
Code that more than one module needs lives in `core/`:
|
||||
|
||||
- `core/common.c` — fingerprinting (kernel version, distro, LSM,
|
||||
hardening flags), logging, error handling
|
||||
- `core/apparmor_bypass.c` — Ubuntu's
|
||||
`apparmor_restrict_unprivileged_userns=1` defeat via
|
||||
`change_onexec("crun")` re-exec
|
||||
- `core/exploit_su.c` — once we have page-cache-write or
|
||||
/etc/passwd-overwrite, this is the shared "drop to root shell"
|
||||
helper
|
||||
- `core/fcrypt.c` — file-encryption helpers used by multiple modules
|
||||
- `core/entrybleed.c` (planned, Phase 3) — kbase leak primitive that
|
||||
any module needing KASLR-defeat can call
|
||||
|
||||
## Top-level dispatcher
|
||||
|
||||
`iamroot.c` (planned, Phase 1) is the CLI entry point. Responsibilities:
|
||||
|
||||
1. Parse args (`--scan`, `--exploit <name>`, `--mitigate`,
|
||||
`--detect-rules`, `--cleanup`, etc.)
|
||||
2. Fingerprint the host
|
||||
3. For `--scan`: iterate module registry, call each module's
|
||||
`detect()`, emit table of results
|
||||
4. For `--exploit <name>`: locate module, gate behind `--i-know`,
|
||||
call its `exploit()`
|
||||
5. For `--detect-rules`: walk module registry, concatenate detection
|
||||
files in the requested format
|
||||
|
||||
## CI matrix
|
||||
|
||||
`.github/workflows/ci.yml` (planned, Phase 4) runs each module's
|
||||
test against a matrix of distro × kernel VMs. Each test asserts:
|
||||
|
||||
- on a vulnerable VM: `detect()` returns 1, `exploit()` returns 0
|
||||
and produces uid=0
|
||||
- on a patched VM: `detect()` returns 0, `exploit()` either refuses
|
||||
or fails gracefully
|
||||
|
||||
Failures on a previously-working matrix entry open an issue
|
||||
automatically (likely cause: distro shipped a backport that broke
|
||||
the module).
|
||||
|
||||
## Adding a new CVE
|
||||
|
||||
1. `git checkout -b add-cve-XXXX-NNNN`
|
||||
2. `cp -r modules/_stubs/_template modules/<module_name>`
|
||||
3. Fill in `MODULE.md`, `NOTICE.md`, `kernel-range.json`
|
||||
4. Implement `module.c` exposing the `iamroot_module` interface
|
||||
5. Ship at least one detection rule under `detect/`
|
||||
6. Add tests under `tests/`
|
||||
7. PR. CI runs the matrix. If it lands root on at least one
|
||||
vulnerable matched VM AND fails cleanly on a patched VM, it
|
||||
merges.
|
||||
|
||||
See `docs/module-template.md` (planned) for the per-module checklist.
|
||||
@@ -0,0 +1,75 @@
|
||||
# Ethics, scope, and acceptable use
|
||||
|
||||
## Acceptable use
|
||||
|
||||
IAMROOT is intended for:
|
||||
|
||||
1. **Authorized red-team / pentest engagements.** You have a written
|
||||
scope, signed by someone who can authorize testing on the target
|
||||
systems.
|
||||
2. **Defensive teams testing detection coverage.** You're using
|
||||
IAMROOT in a lab to verify your auditd/sigma/falco rules fire as
|
||||
expected.
|
||||
3. **Security researchers studying historical LPEs.** You're reading
|
||||
the code, running it in your own VMs, learning how the primitives
|
||||
actually work end-to-end.
|
||||
4. **Build engineers verifying patch coverage.** You're running
|
||||
`iamroot --scan` against your fleet's golden images to confirm
|
||||
each known CVE shows up as patched.
|
||||
|
||||
## Not-acceptable use
|
||||
|
||||
IAMROOT should not be used:
|
||||
|
||||
1. On systems you do not own and have not been authorized to test
|
||||
2. As part of unauthorized access to any system
|
||||
3. To exfiltrate data or maintain persistence on a system after a
|
||||
testing engagement is complete
|
||||
4. To build a worm, scanner, or any tool that automatically targets
|
||||
systems at scale without per-target authorization
|
||||
|
||||
By using IAMROOT you assert that your use falls into the
|
||||
acceptable-use cases above.
|
||||
|
||||
## Why this is publishable
|
||||
|
||||
Every CVE bundled in IAMROOT is:
|
||||
|
||||
- **Already patched** in upstream mainline kernel
|
||||
- **Already published** in NVD or distro security trackers
|
||||
- **Already covered** by existing public PoCs
|
||||
|
||||
IAMROOT does not introduce new offensive capability. It bundles,
|
||||
documents, and CI-tests what is already public — and ships the
|
||||
detection signatures defenders need to spot it.
|
||||
|
||||
The bundling itself raises the baseline competence required to
|
||||
benefit from this code: a script kiddie can already find and run
|
||||
single-CVE PoCs on GitHub. Bundling improves quality and CI coverage
|
||||
without meaningfully changing offensive capability, while providing
|
||||
real defensive value through the detection-rule exports.
|
||||
|
||||
## Disclosure
|
||||
|
||||
If you find a bug in IAMROOT itself (incorrect detection, broken
|
||||
exploit on a kernel where it should work, missing a backport in the
|
||||
range metadata): file a public GitHub issue.
|
||||
|
||||
If you find a **new 0-day kernel LPE while inspired by reading
|
||||
IAMROOT code**: please disclose it responsibly to the kernel
|
||||
security team (`security@kernel.org`) and the affected distros
|
||||
*before* writing a public PoC. Once upstream patch ships and a CVE
|
||||
is assigned, IAMROOT will gladly accept the module.
|
||||
|
||||
## Persistence and stealth are out of scope
|
||||
|
||||
`--exploit-backdoor` in the copy_fail module overwrites a
|
||||
`/etc/passwd` line with a `uid=0` shell account. This is **overt**:
|
||||
|
||||
- The username is `iamroot` (was `dirtyfail`) — instantly identifiable
|
||||
- It's covered by the auditd rules IAMROOT ships
|
||||
- `--cleanup-backdoor` restores the original line
|
||||
|
||||
If you're looking for evasion, persistence, or stealth: not here.
|
||||
Use a real C2 framework if you have authorization to do so. IAMROOT
|
||||
stops at "demonstrate that the bug works."
|
||||
Reference in New Issue
Block a user