Crate isr_cache 

Opinionated cache for OS kernel profiles

This crate provides a caching mechanism for profiles generated and used by the isr crate family. It offers several features to streamline the process of accessing and managing symbol information, including methods for downloading necessary debug symbols for Windows (PDB files) and Linux (DWARF debug info and system map).

Usage

The main component of this crate is the IsrCache struct.

Example of loading a profile from a PDB file using the CodeView information:

use isr_cache::{CodeView, IsrCache};

// Create a new cache instance.
let cache = IsrCache::new("cache")?;

// Use the CodeView information of the Windows 10.0.18362.356 kernel.
let codeview = CodeView {
    name: String::from("ntkrnlmp.pdb"),
    guid: String::from("ce7ffb00c20b87500211456b3e905c47"),
    age: 1,
};

// Fetch and create (or get existing) the entry.
let entry = cache.entry_from_codeview(codeview)?;

// Get the profile from the entry.
let profile = entry.profile()?;

Example of loading a profile based on a Linux kernel banner:

use isr_cache::IsrCache;

// Create a new cache instance.
let cache = IsrCache::new("cache")?;

// Use the Linux banner of the Ubuntu 6.8.0-40.40~22.04.3-generic kernel.
let banner = "Linux version 6.8.0-40-generic \
              (buildd@lcy02-amd64-078) \
              (x86_64-linux-gnu-gcc-12 (Ubuntu 12.3.0-1ubuntu1~22.04) \
              12.3.0, GNU ld (GNU Binutils for Ubuntu) 2.38) \
              #40~22.04.3-Ubuntu SMP PREEMPT_DYNAMIC \
              Tue Jul 30 17:30:19 UTC 2 \
              (Ubuntu 6.8.0-40.40~22.04.3-generic 6.8.12)";

// Fetch and create (or get existing) the entry.
// Note that the download of Linux debug symbols may take a while.
let entry = cache.entry_from_linux_banner(banner)?;

// Get the profile from the entry.
let profile = entry.profile()?;

Consult the vmi crate for more information on how to download debug symbols for introspected VMs.

Structs

ArtifactPolicy

Per-artifact download and optional extraction policy.

CodeView

Identifies the PDB matching a specific PE binary.

Entry

An entry in the IsrCache.

ImageSignature

Identifies a PE image on a Microsoft symbol server.

IsrCache

A cache for OS kernel profiles.

LinuxBanner

Linux banner.

Profile

A typed view over an archived profile.

ProgressWriter

A Write adapter that optionally reports progress.

SymbolDownloader

Downloads PDBs and PE binaries from one or more Microsoft symbol servers.

UbuntuSymbolDownloader

Downloads Ubuntu kernel + debug symbol .deb packages.

UbuntuSymbolPaths

Result of a download() call. Mirrors the request structurally: if the request had Some(policy) for an artifact, the response has Some(paths).

UbuntuSymbolRequest

A request for one or more kernel artifacts.

UbuntuVersionSignature

Ubuntu kernel version signature, as embedded in the UTS version string.

Enums

Error

Error type for the ISR cache.

FilenamePolicy

How to name a file on disk.

LinuxVersionSignature

Distribution-specific version signature extracted from a kernel banner.

ProgressContext

Distinguishes download vs extraction context for ProgressWriter.

ProgressEvent

Progress event emitted during download and extraction operations.

SymbolRequest

A single artifact to fetch from a Microsoft symbol server.

Constants

PROFILE_FILE_EXTENSION

File extension of cached rkyv-serialized Profiles.

Type Aliases

ProgressFn

Shared, cloneable progress callback.