Skip to content

CONTRIBUTING.EN.md

Latest commit

 

History

History
159 lines (113 loc) · 5.47 KB

CONTRIBUTING.EN.md

File metadata and controls

159 lines (113 loc) · 5.47 KB
Raw

Contributing to Kernel Module Examples

Thanks for wanting to contribute! This repository is an open educational resource for the cybersecurity community and anyone learning kernel-level programming.

For general information about the repository, see README.EN.md.

Untuk versi Bahasa Indonesia, lihat CONTRIBUTING.md.

Repository Goal

This repository collects sample code and skeletons for building Kernel Modules across platforms (Linux, FreeBSD, Solaris, Windows). Every example:

  • focuses on a single concept (skeleton, memory allocation, syscall hooking, char/block driver, etc).
  • is concise and compiles directly with the instructions provided.
  • includes comments explaining the concept, not just bare code.

How to Contribute

1. Fork and Clone

git clone https://github.com/YOUR_USERNAME/KernelModule-Examples.git
cd KernelModule-Examples

2. Create a New Branch

git checkout -b add/example-name
git checkout -b fix/short-description
git checkout -b improve/documentation

3. Directory Structure and Naming Convention

platform/
├── basics/                    # core LKM concepts (no device involved)
│   └── N.concept-name/          # e.g. 0.skeleton, 1.hello, 2.memory-alloc
│       ├── code.c
│       └── Makefile
├── drivers/
│   ├── char/                   # character device driver
│   │   └── N.concept-name/
│   └── block/                  # block device driver
│       └── N.concept-name/
├── payload/                    # rootkit-style payload (if relevant to the platform)
│   └── payload-name/
├── README.md / README.EN.md
├── _introduction.md / .EN.md   # core kernel module concepts on this platform
├── _preparation.md / .EN.md    # toolchain & build environment setup
└── _commands.md / .EN.md       # operational command cheat-sheet

Naming conventions:

  • Example directories get a numeric prefix and a short name: 0.skeleton, 1.hello, 2.memory-alloc. The number marks a suggested learning order (simplest first), not the order it was added.
  • Use code.c (or code.cpp for Windows) as the main source file name.
  • Use test.c for a companion user-space program (e.g. to exercise an IOCTL).
  • Use a hyphen (-) to separate words in directory names, all lowercase: memory-alloc, hook-syscall.
  • Supporting doc files get an underscore prefix (_introduction.md, etc.) so they sort visually apart from example directories.

4. Header Comment Template for New code.c Files

Every example must have a header comment following this format (adjust the relevant parts for the target platform):

/*
    Concept Name
    Archive of Reversing.ID

    Tested on <OS Name + Kernel Version>

    Short explanation: what this example demonstrates.

Build:
    $ make

Module info:
    $ modinfo code.ko

List module:
    $ lsmod

Load:
    $ insmod code.ko

Unload:
    $ rmmod code
*/

Adjust the Build/Load/Unload section for the platform's tooling (kldload/kldunload for BSD, modload/modunload for Solaris, sc create/sc start for Windows, etc — see existing examples on the relevant platform).

If there are extra testing steps (e.g. writing to a device file, sending a signal, running a user-space program), add a Testing: section between Load: and Unload:.

5. Coding Guidelines (C/C++)

  • Follow the style already used in the same platform directory (4-space indentation, opening brace on its own line for functions, a space before the parenthesis on function calls).
  • Function and variable naming: snake_case.
  • Comment the parts that explain the concept (why this API is used, what it does at the kernel level), not comments that just restate the function name.
  • Every module must have symmetric init/exit functions — anything allocated or registered at init must be cleaned up at exit.
  • Include a tested Makefile (or project file) — the code must actually compile with the instructions provided.

6. Adding a New Example

Every new example must include:

  1. code.c/code.cpp with a header comment following the template above.
  2. A Makefile (or project file for Windows) with a verified build.
  3. An update to the example table in the relevant platform's README.md/README.EN.md.

7. Testing Before Submitting

  • Compile the code without warnings on the environment named in the header comment.
  • Load and unload the module to confirm there's no crash/panic.
  • Verify there are no broken links in any documentation you changed.

8. Pull Request Process

Before submitting, make sure your branch is up to date:

git fetch origin
git rebase origin/master

PR Description Template

## Description
Short explanation of the change.

## Type of Change
- [ ] New example/platform
- [ ] Improvement to existing code
- [ ] Documentation
- [ ] Bug fix

## Platform/Concept Changed
- Platform: (Linux/BSD/Solaris/Windows)
- Concept: (basics/drivers/payload)

## Checklist
- [ ] Code compiles without warnings
- [ ] Header comment follows the template
- [ ] The relevant platform README was updated
- [ ] No broken links

License

By contributing to this repository, you agree that your contribution may be redistributed as part of this repository. Make sure the code you contribute doesn't infringe on third-party copyright or licenses.

Questions or Help?

  • Open a new issue with the question label.
  • Email pengurus [at] reversing.id
  • Telegram @ReversingID