zond-engine 0.17.0

The core networking library powering Zond. Raw packet injection, protocol parsing, service and OS fingerprinting, and asynchronous network scanning.
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
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
// Copyright (c) 2026 Erik Lening (hollowpointer) and Contributors
//
// This file is part of Zond Engine, licensed under the GNU Affero General
// Public License, version 3 or later. See the LICENSE file for details, or
// <https://www.gnu.org/licenses/agpl-3.0.html>.
//
// SPDX-License-Identifier: AGPL-3.0-or-later

//! # Running compute detections over a port
//!
//! The Tier-2 detection stage, the sibling of [`flow::stage`](crate::detect::flow)
//! and the active counterpart to the [CVE correlator](crate::cve). For a port,
//! every loaded detection whose class the [envelope](crate::config::DetectionEnvelope)
//! permits and whose `when` rule fits is instantiated under its
//! [grant](Grant) and run, and the findings it returns are recorded. It gates on
//! exactly the two questions the [`gate`](crate::detect::gate) module answers, so
//! a compute detection and a flow select ports the same way.
//!
//! ## The capabilities are supplied per port
//!
//! Like the flow stage, this holds no socket of its own: `caps_for` yields the
//! [`Capabilities`] a running detection is served, given the grant it will run
//! under, so a scan hands it a live socket bound to the port and a test hands it a
//! recorded one: the module cannot tell, which is what replay is.
//!
//! ## An abnormal end is not a finding
//!
//! A detection that trapped on a budget, was denied a call, or faulted did not
//! clear the port. It did not finish. That outcome is logged and dropped, never
//! turned into a finding, so a reader never mistakes "ran out of fuel" for "found
//! nothing wrong."

use std::time::Duration;

use tracing::debug;

use crate::config::DetectionEnvelope;
use crate::detect::manifest::DetectionManifest;
use crate::fingerprint::PortContext;
use crate::model::finding::{DetectionId, Finding};
use crate::model::port::Protocol;

use super::budget::{Budget, RunOutcome};
use super::capability::{Capabilities, Grant};
use super::db::ReplayError;
use super::replay::{CapTape, RecordedCapabilities, RecordingCapabilities};
use super::runtime::ComputeRuntime;

/// A compute detection that did not finish cleanly: which detection, and why it
/// ended. The stage returns these beside the findings so the caller can record an
/// inconclusive run rather than dropping it: a run that trapped on a budget or
/// faulted did not clear the port, and a reader must be able to tell the two apart.
pub(crate) struct InconclusiveRun {
    /// The detection whose run did not complete.
    pub(crate) detection: DetectionId,
    /// Why it did not complete.
    pub(crate) outcome: RunOutcome,
    /// The bounds it ran under, so a report can say how large the one it hit
    /// was.
    pub(crate) budget: Budget,
}

/// What a port's compute detections produced: the findings, and the runs that did
/// not finish cleanly. A clean scan leaves [`inconclusive`](Self::inconclusive)
/// empty; anything in it is a detection the report should account for.
pub(crate) struct PortDetections {
    /// The findings the detections drew.
    pub(crate) findings: Vec<Finding>,
    /// The runs that ended abnormally, kept so the caller can surface them.
    pub(crate) inconclusive: Vec<InconclusiveRun>,
}

/// A compute detection compiled and ready to run: its [`DetectionManifest`],
/// its compiled module, and the content hash of the body it came from, which
/// its findings are stamped with as provenance.
pub struct LoadedDetection<M> {
    manifest: DetectionManifest,
    module: M,
    content_hash: String,
}

impl<M> LoadedDetection<M> {
    /// A loaded detection from its parts. The `content_hash` is the body's content
    /// address, computed by whatever sourced it.
    pub fn new(manifest: DetectionManifest, module: M, content_hash: impl Into<String>) -> Self {
        Self {
            manifest,
            module,
            content_hash: content_hash.into(),
        }
    }

    /// The content hash of the detection body, its provenance and the key a
    /// journalled run is matched back to for replay.
    pub(crate) fn content_hash(&self) -> &str {
        &self.content_hash
    }

    /// What the detection declares. The live path matches a run to its detection
    /// by content hash instead; this is for a corpus listing and for tests looking
    /// a shipped detection up by name.
    pub(crate) fn manifest(&self) -> &DetectionManifest {
        &self.manifest
    }
}

/// Runs `detections` over one port, returning the findings they produce.
///
/// `service` is the port's identified service, which the `when` rule may gate on;
/// `ctx` carries the port number, protocol, and address a running detection sees;
/// `responses` are the bytes the scan already gathered. `caps_for` yields the
/// [`Capabilities`] a detection is served under the grant it will run, or [`None`]
/// to skip it. A detection the envelope forbids or whose gate does not fit the
/// port never instantiates.
///
/// Every run is recorded, and its [`CapTape`] is handed to `record` once the run
/// ends, clean or not, so a caller can keep it for a later replay. A caller that
/// does not want the tapes ignores them.
///
/// A run that ends abnormally is not turned into a finding, but it is not dropped
/// either: it is returned in [`PortDetections::inconclusive`] so the caller can
/// record that the detection did not finish, which a report needs to tell apart
/// from a detection that finished and found nothing.
// Eight inputs: the whole per-port situation plus both capability seams. Bundling
// them into a request type is a later cleanup shared with the flow stage.
#[allow(clippy::too_many_arguments)]
pub(crate) fn detect_port<R: ComputeRuntime>(
    runtime: &R,
    detections: &[LoadedDetection<R::Module>],
    envelope: &DetectionEnvelope,
    service: Option<&str>,
    ctx: &PortContext,
    responses: &[&[u8]],
    mut caps_for: impl FnMut(&Grant) -> Option<Box<dyn Capabilities>>,
    mut record: impl FnMut(&Grant, CapTape),
) -> PortDetections {
    let mut findings = Vec::new();
    let mut inconclusive = Vec::new();
    for detection in detections {
        let Some(grant) = Grant::from_manifest(&detection.manifest, &detection.content_hash) else {
            continue;
        };
        if !envelope.permits(grant.class)
            || !detection
                .manifest
                .when
                .applies(service, ctx.port, ctx.protocol)
        {
            continue;
        }

        let mut instance = match runtime.instantiate(&detection.module, &grant) {
            Ok(instance) => instance,
            Err(error) => {
                debug!(
                    detection = grant.detection.id(),
                    ?error,
                    "a compute detection could not be instantiated"
                );
                continue;
            }
        };
        let Some(caps) = caps_for(&grant) else {
            continue;
        };
        let mut recording = RecordingCapabilities::new(caps);

        match runtime.run(&mut instance, ctx, responses, &mut recording) {
            Ok(produced) => findings.extend(produced),
            Err(outcome) => {
                debug!(
                    detection = grant.detection.id(),
                    ?outcome,
                    "a compute detection ended without a clean result"
                );
                inconclusive.push(InconclusiveRun {
                    detection: grant.detection.clone(),
                    outcome,
                    budget: grant.budget,
                });
            }
        }
        record(&grant, recording.into_tape());
    }
    PortDetections {
        findings,
        inconclusive,
    }
}

/// Replays one detection over a recorded [`CapTape`], reproducing the findings the
/// recorded run produced with no network.
///
/// Where [`detect_port`] serves a live socket, this serves the tape, so the same
/// module reads the same bytes and reaches the same verdict offline. It does not
/// gate on the envelope: the run already happened and passed the gate live, so this
/// reproduces it rather than deciding again.
pub(crate) fn replay_over_tape<R: ComputeRuntime>(
    runtime: &R,
    detection: &LoadedDetection<R::Module>,
    ctx: &PortContext,
    responses: &[&[u8]],
    tape: CapTape,
) -> Result<Vec<Finding>, ReplayError> {
    let Some(mut grant) = Grant::from_manifest(&detection.manifest, &detection.content_hash) else {
        return Err(ReplayError::GrantFailed);
    };
    // Replay reads its I/O from the tape, so it does no network work and finishes
    // in its own time. Leaving the live wall-clock deadline in place would let a
    // slow replay host trap a run the recording did not, so a fast machine and a
    // slow one would disagree about the findings. Fuel still bounds it, the same
    // deterministic count the recording ran under.
    grant.budget.deadline = Duration::from_secs(86_400);
    let mut instance = runtime
        .instantiate(&detection.module, &grant)
        .map_err(ReplayError::Instantiate)?;
    let mut caps = RecordedCapabilities::from_tape(tape);
    let findings = runtime
        .run(&mut instance, ctx, responses, &mut caps)
        .map_err(ReplayError::Run)?;
    // A faithful replay reads the tape exactly; reading past its end means the tape
    // was too short to reproduce the run, so the findings are not the recorded ones.
    if caps.diverged() {
        return Err(ReplayError::Diverged);
    }
    Ok(findings)
}

/// Whether any loaded detection the envelope permits gates onto a port with these
/// facts, so a caller can skip a port no compute detection would run over.
pub(crate) fn interested<M>(
    detections: &[LoadedDetection<M>],
    envelope: &DetectionEnvelope,
    service: Option<&str>,
    number: u16,
    protocol: Protocol,
) -> bool {
    detections.iter().any(|detection| {
        Grant::from_manifest(&detection.manifest, &detection.content_hash).is_some_and(|grant| {
            envelope.permits(grant.class)
                && detection.manifest.when.applies(service, number, protocol)
        })
    })
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::detect::compute::{CapError, ModuleBody, RhaiRuntime, ScanInstant};
    use crate::detect::manifest::{CapabilitySpec, Class, Rule, Speak};
    use crate::model::finding::{DetectionClass, Severity};
    use crate::model::port::Protocol;
    use std::net::IpAddr;

    /// A stand-in socket that answers every probe with one banner, so an active
    /// detection has something to decide on and a passive one ignores it.
    struct StubCaps;
    impl Capabilities for StubCaps {
        fn speak(&mut self, _bytes: &[u8]) -> Result<Vec<u8>, CapError> {
            Ok(b"# Server".to_vec())
        }
        fn resolve(&mut self, _name: &str) -> Result<Vec<IpAddr>, CapError> {
            Ok(Vec::new())
        }
        fn now(&mut self) -> ScanInstant {
            ScanInstant::from_millis(0)
        }
    }

    /// A passive detection that fires whenever it runs, so a finding is proof the
    /// stage chose to run it.
    const ALWAYS: &str = r#"
        fn analyze(ctx, responses) {
            [ #{ severity: "medium", summary: "port " + ctx.port } ]
        }
    "#;

    fn loaded(
        runtime: &RhaiRuntime,
        id: &str,
        service: &str,
        class: Class,
        source: &str,
    ) -> LoadedDetection<<RhaiRuntime as ComputeRuntime>::Module> {
        let manifest = DetectionManifest {
            id: id.to_string(),
            version: "1.0.0".to_string(),
            title: id.to_string(),
            when: Rule {
                service: Some(service.to_string()),
                services: Vec::new(),
                port: None,
                ports: Vec::new(),
                protocol: None,
                speaks: None,
            },
            capabilities: CapabilitySpec {
                class,
                speak: Some(Speak::Target),
                resolve: false,
                max_bytes: None,
                max_millis: None,
                max_connections: None,
            },
        };
        let module = runtime
            .load(&ModuleBody::Rhai(source.to_string()))
            .expect("the module compiles");
        LoadedDetection::new(manifest, module, "hash")
    }

    fn ctx(port: u16) -> PortContext {
        PortContext {
            port,
            protocol: Protocol::Tcp,
            addr: None,
            tunnel: None,
            speaks_http: false,
            detection: crate::config::ServiceDetection::default(),
        }
    }

    #[test]
    fn only_the_detection_whose_gate_fits_the_port_runs() {
        let runtime = RhaiRuntime::new();
        let detections = vec![
            loaded(&runtime, "redis-check", "redis", Class::Passive, ALWAYS),
            loaded(&runtime, "http-check", "http", Class::Passive, ALWAYS),
        ];

        let findings = detect_port(
            &runtime,
            &detections,
            &DetectionEnvelope::default(),
            Some("redis"),
            &ctx(6379),
            &[],
            |_grant| Some(Box::new(StubCaps)),
            |_, _| {},
        )
        .findings;

        assert_eq!(findings.len(), 1, "only the redis gate fit the port");
        assert_eq!(findings[0].detection().id(), "redis-check");
    }

    #[test]
    fn the_envelope_decides_whether_an_intrusive_detection_runs() {
        let runtime = RhaiRuntime::new();
        let detections = vec![loaded(&runtime, "exploit", "redis", Class::Exploit, ALWAYS)];

        // Off by default: the exploit class is above the default ceiling.
        let withheld = detect_port(
            &runtime,
            &detections,
            &DetectionEnvelope::default(),
            Some("redis"),
            &ctx(6379),
            &[],
            |_grant| Some(Box::new(StubCaps)),
            |_, _| {},
        )
        .findings;
        assert!(
            withheld.is_empty(),
            "an exploit ran under the default envelope"
        );

        // The operator raises the ceiling to it, and the same detection runs.
        let permitted = detect_port(
            &runtime,
            &detections,
            &DetectionEnvelope::up_to(DetectionClass::Exploit),
            Some("redis"),
            &ctx(6379),
            &[],
            |_grant| Some(Box::new(StubCaps)),
            |_, _| {},
        )
        .findings;
        assert_eq!(permitted.len(), 1, "an opted-in exploit did not run");
    }

    #[test]
    /// Named rather than defaulted: the default ceiling reads what a scan
    /// gathered and permits nothing that opens a connection, which is the whole
    /// of what this test is about.
    fn an_active_detection_is_served_its_socket_and_decides_on_the_reply() {
        let runtime = RhaiRuntime::new();
        // Speaks, and fires only because the stub answered.
        let source = r#"
            fn analyze(ctx, responses) {
                let reply = speak(blob(1, 0x41));
                if reply.len() > 0 {
                    [ #{ severity: "high", summary: "the port answered" } ]
                } else {
                    []
                }
            }
        "#;
        let detections = vec![loaded(
            &runtime,
            "active",
            "redis",
            Class::ActiveBenign,
            source,
        )];

        let findings = detect_port(
            &runtime,
            &detections,
            &DetectionEnvelope::up_to(DetectionClass::ActiveBenign),
            Some("redis"),
            &ctx(6379),
            &[],
            |_grant| Some(Box::new(StubCaps)),
            |_, _| {},
        )
        .findings;

        assert_eq!(findings.len(), 1);
        assert_eq!(findings[0].severity(), Severity::High);
    }

    #[test]
    fn a_passive_detection_that_reaches_for_speak_produces_nothing() {
        // The grant gives a passive detection no `speak`, so a passive body that
        // names it faults and emits nothing, the class enforced at the stage.
        let runtime = RhaiRuntime::new();
        let source = r#"
            fn analyze(ctx, responses) {
                speak(blob(1, 0x41));
                [ #{ severity: "high", summary: "should never be reached" } ]
            }
        "#;
        let detections = vec![loaded(&runtime, "sneaky", "redis", Class::Passive, source)];

        let findings = detect_port(
            &runtime,
            &detections,
            &DetectionEnvelope::default(),
            Some("redis"),
            &ctx(6379),
            &[],
            |_grant| Some(Box::new(StubCaps)),
            |_, _| {},
        )
        .findings;

        assert!(
            findings.is_empty(),
            "a passive detection reached the network"
        );
    }

    #[test]
    /// The ceiling is named for the reason the test above names one: a tape is
    /// what a module's socket work leaves behind, and the default ceiling grants
    /// none.
    fn a_run_is_recorded_and_its_tape_handed_back() {
        // An active detection that speaks once. The tape the stage captures must
        // hold that exchange, so a later replay can reproduce the run.
        let runtime = RhaiRuntime::new();
        let source = r#"
            fn analyze(ctx, responses) {
                let reply = speak(blob(1, 0x41));
                if reply.len() > 0 {
                    [ #{ severity: "high", summary: "the port answered" } ]
                } else {
                    []
                }
            }
        "#;
        let detections = vec![loaded(
            &runtime,
            "active",
            "redis",
            Class::ActiveBenign,
            source,
        )];

        let mut tapes = Vec::new();
        let findings = detect_port(
            &runtime,
            &detections,
            &DetectionEnvelope::up_to(DetectionClass::ActiveBenign),
            Some("redis"),
            &ctx(6379),
            &[],
            |_grant| Some(Box::new(StubCaps)),
            |_grant, tape| tapes.push(tape),
        )
        .findings;

        assert_eq!(findings.len(), 1);
        assert_eq!(tapes.len(), 1, "the run's tape was not handed back");
        assert_eq!(tapes[0].speaks.len(), 1, "the speak was not recorded");
        assert_eq!(
            tapes[0].speaks[0].reply,
            Ok(b"# Server".to_vec()),
            "the recorded reply is not what the socket returned"
        );
    }

    #[test]
    fn a_recorded_run_replays_an_active_detection_offline() {
        // The offline replay: an active detection that decides on a socket reply is
        // reproduced from its tape alone, no network. The recorded reply drives the
        // finding exactly as the live one did.
        use crate::detect::compute::SpeakExchange;

        let runtime = RhaiRuntime::new();
        let source = r#"
            fn analyze(ctx, responses) {
                let reply = speak(blob(1, 0x41));
                if reply.len() > 0 {
                    [ #{ severity: "high", summary: "the port answered" } ]
                } else {
                    []
                }
            }
        "#;
        let detection = loaded(&runtime, "active", "redis", Class::ActiveBenign, source);
        let tape = CapTape {
            speaks: vec![SpeakExchange {
                sent: vec![0x41],
                reply: Ok(b"# Server".to_vec()),
            }],
            ..Default::default()
        };

        let findings = replay_over_tape(&runtime, &detection, &ctx(6379), &[], tape)
            .expect("the recorded run replays");
        assert_eq!(findings.len(), 1, "the recorded run did not replay");
        assert_eq!(findings[0].severity(), Severity::High);
    }

    #[test]
    fn a_replay_over_a_short_tape_reports_divergence_rather_than_a_finding() {
        // A module that speaks twice, replayed against a one-entry tape: the second
        // speak reads past the end, so the replay diverged from the recorded run and
        // its findings are not the recorded ones.
        use crate::detect::compute::SpeakExchange;
        let runtime = RhaiRuntime::new();
        let source = r#"
            fn analyze(ctx, responses) {
                let a = speak(blob(1, 0x41));
                let b = speak(blob(1, 0x42));
                if a.len() > 0 && b.len() > 0 {
                    [ #{ severity: "high", summary: "both answered" } ]
                } else {
                    []
                }
            }
        "#;
        let detection = loaded(&runtime, "two-speaks", "redis", Class::ActiveBenign, source);
        let short = CapTape {
            speaks: vec![SpeakExchange {
                sent: vec![0x41],
                reply: Ok(b"yes".to_vec()),
            }],
            ..Default::default()
        };

        let outcome = replay_over_tape(&runtime, &detection, &ctx(6379), &[], short);
        assert_eq!(
            outcome,
            Err(ReplayError::Diverged),
            "a short tape must report divergence, not a clean empty run"
        );
    }

    #[test]
    fn a_faulting_detection_is_returned_as_inconclusive_not_a_finding() {
        // A module that throws did not clear the port; it did not finish. The stage
        // must hand that back as an inconclusive run, naming the detection and why,
        // rather than dropping it into a log where the report cannot see it.
        let runtime = RhaiRuntime::new();
        let source = r#"
            fn analyze(ctx, responses) {
                throw "deliberate fault";
            }
        "#;
        let detections = vec![loaded(&runtime, "faulty", "redis", Class::Passive, source)];

        let result = detect_port(
            &runtime,
            &detections,
            &DetectionEnvelope::default(),
            Some("redis"),
            &ctx(6379),
            &[],
            |_grant| Some(Box::new(StubCaps)),
            |_, _| {},
        );

        assert!(
            result.findings.is_empty(),
            "a fault must not be reported as a finding"
        );
        assert_eq!(result.inconclusive.len(), 1, "the fault was not surfaced");
        assert_eq!(result.inconclusive[0].detection.id(), "faulty");
        assert!(
            matches!(result.inconclusive[0].outcome, RunOutcome::Faulted(_)),
            "the outcome was not a fault: {:?}",
            result.inconclusive[0].outcome
        );
    }
}