Kass

Kass is a collection of modules for reverse-engineering and security research on macOS, written in Swift. It is currently focused on interacting with the XNU kernel which underlies macOS, but may be expanded in the future to support other XNU-based operating systems such as iOS.

Note that while it may compile on older versions of macOS, this library is only thoroughly tested on the latest version of macOS. In some cases, older deprecated (or even obsoleted) API's are included, but they should be assumed to be untested as it stands today. This may change in the future.

A Message From The Developer

Hi! This is nmggithub, the sole developer of this project. I tend to avoid using pronouns in general when it comes to documentation, but I realized I couldn't really avoid it here, so this section is going to be a lot more personal than any of the other documentation. Perhaps I may change my style in the future, but for now this is going to stand out, so I thought I'd address it.

Anyway, this library is currently, as of writing on version 3.0.0. After months of work and multiple refactors, it's here. Kass 3.0.0 is a major upgrade from Kass 2.0.0, hence the major version change. But even now, it's still a library in transition. Hopefully not in the architecture department, but Kass 3.0.0 is still missing several features I wish I could have included.

Going forward, I want to try and stick with Semantic Versioning, but I don't think I can commit to that fully (especially with how often my mind changes). I honestly don't know how many (if anyone) is using this project, but I want 3.0 onward to be at least somewhat stable.

I consider the MachCore module to be mostly stable, so there will likely be little changes to it going forward (save for the addition of virtual memory API's). BSDCore is in its early stages, so a lot can change there. Finally, Linking will likely be folded into BSDCore at some point.

I hope this library is of some use to you, and I look forward to more stable releases in the future. If you have any issues with it, feel free to file an issue. If you'd like to contribute, go ahead and open a PR. I appreciate all the feedback and support.

On Licenses

Most of this code is MIT-licensed. However, there are some cases where substance is copied from header files licensed under Apple's Public Source License and other licenses. Where deemed appropriate, copyright notices for the relevant licenses are included. Please see the source code for more information.

Modules

Kass

This is merely a namespace "module". It can be used to access the the MachCore and BSDCore modules, but is not strictly necessary.

MachCore

This module provides facilities for interacting with the Mach portion of the XNU kernel. Most Mach API's are provided, although some are intentionally left in specific cases. Virtual memory API's are largely left out but are planned for a later release. This module should be considered the most stable, as it has had the most work put into it.

BSDCore

This module provides facilities for interacting with the Mach portion of the XNU kernel. It is very much a work-in-progress and should not be considered very stable as it may be subject to change.

Linking

This module provides a simple API to access symbols that uses the dlopen/dlsym functions internally. It will likely be folded into BSDCore at some point.

Notes

Please note that these modules are meant primarily for reverse-engineering and security research. While some of these modules can be useful in production apps, that is not their intended purpose.

Usage

Adding the dependency:

Modify your Package.swift like so:

let package = Package(
  ...
  dependencies: [
    .package(url: "https://github.com/nmggithub/Kass", exact: "{desired-version}"),
  ],
  targets: [
    /// the target you wish to use this module in
    .[target | executableTarget](
      ...
      dependencies: [
        .product(name: "{module-name}", package: "Kass")
      ]
    )
  ]
)

Using the dependency in the target:

Simply put

import {module-name}

at the top of your Swift file.

Naming collisions

If any module names collides with existing modules in your package, simply use the moduleAliases: option when defining the dependency. Please see the documentation for any additional information on naming collisions.