linux-exploit-primitive-summary

name	linux-exploit-primitive-summary
description	Summarize Linux kernel exploit primitives into the standard format used by ingots_tools/primitives/. Use when extracting a reusable primitive (like a heap spray, info leak technique, or corruption primitive) from a PoC or exploit description.

Linux Exploit Primitive Summary

This skill guides you through summarizing a Linux kernel exploit primitive into a structured format for inclusion in the ingots_tools/primitives/ library.

Workflow

1. Analyze the Source: Identify the core primitive in the exploit PoC or description. Look for specific techniques (e.g., setxattr spray, userfaultfd wait, pipe_buffer overwrite).
2. Extract Logic: Isolate the code necessary to initialize, trigger, and clean up the primitive.
3. Structure the Data: Create the following directory structure: ingots_tools/primitives/src/primitive_data/<primitive_name>/
   • metadata.json: Metadata about the primitive.
   • PRIMITIVE.md: Human-readable documentation.
   • primitive.c: Clean, standalone C implementation.

File Formats

1. metadata.json

Required fields:

• name: Short, hyphen-cased or snake-cased name.
• description: One or two sentences explaining the primitive's effect.
• target: Target kernel type ("linux", "android", or "any")
• arch: List of supported architectures (e.g., ["amd64", "arm64", "x86" (32 bit x86)]).
• version: optional version of linux which the primitive targets (e.g., "any", "v5.10+", "< v6.0")

2. PRIMITIVE.md

Sections to include:

• Title: # <Primitive Name> Primitive
• Description: Detailed explanation of how the primitive works at the kernel level.
• Preconditions: Provide details about which preconditions are needed in order to use thie primitive.
• Usage: Step-by-step instructions on how to use the C API provided in primitive.c.
• Key Concepts: Bullet points highlighting critical details (e.g., SLAB cache used, specific syscalls, timing constraints).

3. primitive.c

• Use clean, modular C code.
• Prefer a "Context/Object" based approach (a struct representing the primitive state).
• Implement standard functions: init_<name>, execute_<name>, and cleanup_<name>.
• Use _GNU_SOURCE and standard headers.

Location

You must place these 3 files in a subdirectory in the ingots_tools/primitives/src/primitive_data directory. Name the subdirector using snake_case and use a name which is a short title describing the primitive (1 - 5 words or so).

Reference Example

See references/example.md for a complete example of the pipe_spray primitive.