cradle-plugin-api 0.1.0

API for cradle plugins
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131

# `cradle-plugin-api`

This crate is intended for use when developing plugins for the Cradle agent
Documentation of the available functions is located in the [docs.rs](https://docs.rs/crate/cradle-plugin-api/) page.

> [!WARNING]
> Every plugin must implement `Default`, as the registration macro relies on it.
> Plugins must also be compiled as `cdylib` crates.

## Cargo.toml

```toml
[package]
name = "my-cradle-plugin"
version = "0.1.0"
edition = "2024"

[lib]
crate-type = ["cdylib"]

[dependencies]
cradle-plugin-api = "0.1"
cradle-shared = "0.1"
```

## Minimal plugin

```rust
use cradle_plugin_api::*;

struct TestPlugin {
    results: PluginResults,
}

impl Default for TestPlugin {
    fn default() -> Self {
        Self {
            results: PluginResults::new("test-plugin"),
        }
    }
}

impl CradlePlugin for TestPlugin {
    fn name(&self) -> &str {
        "test-plugin"
    }

    fn on_event(&mut self, event: &AgentEvent) -> CradleResult {
        if let AgentEvent::ProcessCreated { target_path, .. } = event {
            self.results
                .pass("process-created", format!("process created: {target_path}"));
        }

        Ok(())
    }

    fn results(&mut self) -> Vec<CheckResult> {
        self.results.take()
    }
}

register_plugin!(TestPlugin);
```

## Emitting results

`PluginResults` helps build check output with the plugin name filled in
Use `take()` in your `results()` implementation so each result is returned only once

```rust
self.results.pass("loaded", "plugin initialized successfully");
self.results.info("target", "received process metadata");
self.results.warn_with("network", "direct IP connection observed", "no DNS event matched it");
self.results.fail("policy", "blocked behavior detected");
```

## Hooking an export

Plugins that need runtime inspection can install hooks during `init`
Hooking is unsafe because it reads and writes target process memory

```rust
use cradle_plugin_api::*;

struct HookPlugin {
    results: PluginResults,
}

impl Default for HookPlugin {
    fn default() -> Self {
        Self {
            results: PluginResults::new("hook-plugin"),
        }
    }
}

impl CradlePlugin for HookPlugin {
    fn name(&self) -> &str {
        "hook-plugin"
    }

    fn init(&mut self, engine: CradleMutex<cradle_hooks::HookEngine>) -> CradleResult {
        unsafe {
            engine.lock().hook_export("kernel32.dll", "CreateFileW", Box::new(|ctx| {
                let file_name_ptr = ctx.arg(0);
                let file_name = ctx.read_wide_string(file_name_ptr, 512);

                clog!("CreateFileW called for {file_name}");

                Ok(cradle_hooks::HookAction::Continue)
            }))
        }
    }

    fn results(&mut self) -> Vec<CheckResult> {
        self.results.take()
    }
}

register_plugin!(HookPlugin);
```

## Logging

Use `clog!` for general plugin logs or `plog!(self, "...")` to prefix logs with the plugin name.
Logs are stored by the plugin API and drained by the agent.

## ABI exports

Use `register_plugin!(YourPluginType)` unless you are intentionally implementing the raw FFI boundary yourself.
The macro exports the required symbols for API versioning, lifecycle callbacks, result transfer, and plugin-owned string cleanup.