eggsec-nse 0.3.0

Standalone Lua-based Nmap Scripting Engine runtime
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
//! Canonical NSE execution pipeline.
//!
//! This module owns the single authoritative runtime path from an
//! [`NseRunRequest`] (target, script source, profile, optional host/port
//! context, explicit limit/cancellation overrides) through script resolution,
//! executor setup, rule/action execution, and complete [`NseRunReport`]
//! assembly.
//!
//! Production surfaces (runtime CLI helper, Eggsec dispatch/TUI, Python
//! bindings) must select a request/profile and render the returned report.
//! They must not reproduce this orchestration.
//!
//! NSE runtime capability policy (profile-gated script/module/network
//! behavior) remains distinct from Eggsec operation authorization, which
//! stays outside `eggsec-nse`.

use std::fmt;
use std::sync::LazyLock;

use regex::Regex;
use rustc_hash::FxHashSet;

use crate::context::{NseHostContext, NsePortContext};
use crate::executor::NseExecutor;
use crate::limits::{NseCancellationToken, NseExecutionLimits};
use crate::profile::ResolvedNseExecutionProfile;
use crate::providers::NseHostServices;
use crate::report::{extract_evidence, library_use_reports_from_static_requires, NseRunReport};
use crate::resolver::{NseLoadDiagnostic, NseLoadError, NseScriptSource, ScriptResolver};

/// Canonical runtime-owned execution request.
///
/// Prefer constructing this value over positional executor calls. The
/// resolved execution profile carries sandbox, limits, script/module
/// policy, and network policy; `limits_override` and `cancellation` are
/// the only explicit per-run override seams.
#[derive(Debug, Clone)]
pub struct NseRunRequest {
    /// Target host or URL as supplied by the caller.
    pub target: String,
    /// Script source identity (built-in, registry, file, inline/manual).
    pub script: NseScriptSource,
    /// Optional comma-separated script arguments.
    pub script_args: Option<String>,
    /// Resolved execution profile governing this run.
    pub profile: ResolvedNseExecutionProfile,
    /// Optional host context applied to the executor before execution.
    pub host_context: Option<NseHostContext>,
    /// Optional port context applied to the executor before execution.
    pub port_context: Option<NsePortContext>,
    /// Optional per-run limits replacing `profile.limits`.
    pub limits_override: Option<NseExecutionLimits>,
    /// Optional per-run cancellation token. A fresh token is created when
    /// absent.
    pub cancellation: Option<NseCancellationToken>,
    /// Optional per-run host services. Native providers are used when absent,
    /// preserving existing caller construction.
    pub host_services: Option<NseHostServices>,
}

impl NseRunRequest {
    /// Build a request with no arguments, context, or overrides.
    pub fn new(
        target: &str,
        script: NseScriptSource,
        profile: ResolvedNseExecutionProfile,
    ) -> Self {
        Self {
            target: target.to_string(),
            script,
            script_args: None,
            profile,
            host_context: None,
            port_context: None,
            limits_override: None,
            cancellation: None,
            host_services: None,
        }
    }

    /// Attach script arguments.
    pub fn with_script_args(mut self, args: &str) -> Self {
        self.script_args = Some(args.to_string());
        self
    }

    /// Attach host context applied to the executor before execution.
    pub fn with_host_context(mut self, ctx: NseHostContext) -> Self {
        self.host_context = Some(ctx);
        self
    }

    /// Attach port context applied to the executor before execution.
    pub fn with_port_context(mut self, ctx: NsePortContext) -> Self {
        self.port_context = Some(ctx);
        self
    }

    /// Replace the profile limits for this run only.
    pub fn with_limits_override(mut self, limits: NseExecutionLimits) -> Self {
        self.limits_override = Some(limits);
        self
    }

    /// Use a caller-owned cancellation token for this run.
    pub fn with_cancellation(mut self, token: NseCancellationToken) -> Self {
        self.cancellation = Some(token);
        self
    }

    /// Inject per-run host services (additive; native defaults otherwise).
    ///
    /// Existing `NseRunRequest::new(...)` callers continue to receive native
    /// clock/random/environment behavior unchanged.
    pub fn with_host_services(mut self, services: NseHostServices) -> Self {
        self.host_services = Some(services);
        self
    }

    /// Effective host services: injected bundle or native defaults.
    pub fn effective_host_services(&self) -> NseHostServices {
        self.host_services.clone().unwrap_or_default()
    }

    /// Effective limits: explicit override wins over profile limits.
    pub fn effective_limits(&self) -> NseExecutionLimits {
        self.limits_override
            .clone()
            .unwrap_or_else(|| self.profile.limits.clone())
    }

    /// Effective cancellation token: caller token or a fresh one.
    pub fn effective_cancellation(&self) -> NseCancellationToken {
        self.cancellation.clone().unwrap_or_default()
    }

    /// Script display name derived from the source identity.
    pub fn script_name(&self) -> String {
        script_name_for_source(&self.script)
    }
}

/// Script display name derived from the source identity.
///
/// Used for `NseRunReport.script_name` so every surface reports the same
/// name for the same source.
pub fn script_name_for_source(source: &NseScriptSource) -> String {
    match source {
        NseScriptSource::Builtin { name } => name.clone(),
        NseScriptSource::TrustedRegistry { name } => name.clone(),
        NseScriptSource::File { path } => path
            .file_stem()
            .and_then(|s| s.to_str())
            .unwrap_or("unknown")
            .to_string(),
        NseScriptSource::InlineManual { label, .. } => label.clone(),
    }
}

/// Machine-readable failure kind for a canonical run.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum NseRunErrorKind {
    /// Script resolution failed (policy, missing file, oversized, ...).
    Resolution,
    /// Executor construction failed.
    ExecutorInit,
    /// Target was rejected by the executor.
    TargetRejected,
    /// Script arguments were rejected by the executor.
    ScriptArgsRejected,
    /// Script execution failed.
    Execution,
    /// Cancellation was requested before or during execution.
    Cancelled,
}

impl fmt::Display for NseRunErrorKind {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::Resolution => write!(f, "resolution"),
            Self::ExecutorInit => write!(f, "executor-init"),
            Self::TargetRejected => write!(f, "target-rejected"),
            Self::ScriptArgsRejected => write!(f, "script-args-rejected"),
            Self::Execution => write!(f, "execution"),
            Self::Cancelled => write!(f, "cancelled"),
        }
    }
}

/// Typed failure from the canonical pipeline.
///
/// Carries the request context required to build a failure report where
/// current caller behavior requires one (see [`NseRunError::failure_report`]).
/// Cancellation is never converted into an ordinary successful empty report.
#[derive(Debug, Clone)]
pub struct NseRunError {
    /// Failure kind.
    pub kind: NseRunErrorKind,
    /// Human-readable cause.
    pub message: String,
    /// Request target.
    pub target: String,
    /// Request script name.
    pub script_name: String,
    /// Request script source.
    pub script_source: NseScriptSource,
    /// Effective profile (limits override applied).
    pub profile: ResolvedNseExecutionProfile,
    /// Resolver diagnostics collected before the failure.
    pub diagnostics: Vec<NseLoadDiagnostic>,
}

impl NseRunError {
    fn new(
        kind: NseRunErrorKind,
        message: String,
        request: &NseRunRequest,
        effective_profile: &ResolvedNseExecutionProfile,
        diagnostics: Vec<NseLoadDiagnostic>,
    ) -> Self {
        Self {
            kind,
            message,
            target: request.target.clone(),
            script_name: request.script_name(),
            script_source: request.script.clone(),
            profile: effective_profile.clone(),
            diagnostics,
        }
    }

    /// Build a failure `NseRunReport` preserving profile, source,
    /// resolver diagnostics, and the error.
    ///
    /// Mirrors the pre-convergence failure-report behavior: the report
    /// carries `Failed` compatibility once computed.
    pub fn failure_report(&self) -> NseRunReport {
        NseRunReport::new(&self.target, &self.script_name)
            .with_profile(&self.profile)
            .with_script_source(&self.script_source)
            .with_resolver_diagnostics(&self.diagnostics)
            .with_error(&self.message)
            .compute_compatibility()
    }
}

impl fmt::Display for NseRunError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "NSE {} failed: {}", self.kind, self.message)
    }
}

impl std::error::Error for NseRunError {}

static STATIC_REQUIRE_RE: LazyLock<Regex> = LazyLock::new(|| {
    Regex::new(r#"(?m)\brequire\s*(?:\(\s*)?['"]([^'"]+)['"]\s*\)?"#)
        .expect("static require regex must compile")
});

/// Runtime-owned static `require()` fallback.
///
/// Used only when dynamic require tracking produced no library reports.
/// Entries are labeled `loaded: false` with a static-detection warning via
/// [`library_use_reports_from_static_requires`]; this function is the single
/// owner of that fallback (callers must not duplicate it).
pub fn extract_static_requires(script_content: &str) -> Vec<String> {
    let mut seen = FxHashSet::default();
    let mut names = Vec::new();

    for capture in STATIC_REQUIRE_RE.captures_iter(script_content) {
        let Some(name) = capture.get(1).map(|m| m.as_str().trim()) else {
            continue;
        };
        if name.is_empty() {
            continue;
        }
        let name = name.to_string();
        if seen.insert(name.clone()) {
            names.push(name);
        }
    }

    names
}

/// Execute one canonical NSE run: resolve, execute, assemble, report.
///
/// This is the single owner of the resolver-first execution sequence:
/// 1. resolve the supplied [`NseScriptSource`] using [`ScriptResolver`]
///    and profile policy;
/// 2. initialize the executor with the resolved (effective) profile;
/// 3. set target/script args/optional host-port context;
/// 4. execute NSE rule evaluation and action semantics;
/// 5. gather final execution stats;
/// 6. gather dynamic library-use data plus the runtime-owned static
///    fallback when tracking produced nothing;
/// 7. gather capability events;
/// 8. preserve resolver diagnostics;
/// 9. build the report;
/// 10. compute compatibility/fidelity once;
/// 11. extract evidence once;
/// 12. return the complete report.
///
/// Synchronous and blocking: async callers must run it inside
/// `spawn_blocking` (or an equivalent bounded blocking task). Per-run
/// report state is never shared across concurrent executions.
pub fn execute_nse_run(request: NseRunRequest) -> Result<NseRunReport, NseRunError> {
    let script_name = request.script_name();
    let mut effective_profile = request.profile.clone();
    if let Some(ref limits) = request.limits_override {
        effective_profile.limits = limits.clone();
    }
    let cancellation = request.effective_cancellation();

    if cancellation.is_cancelled() {
        return Err(NseRunError::new(
            NseRunErrorKind::Cancelled,
            "cancellation requested before execution".to_string(),
            &request,
            &effective_profile,
            Vec::new(),
        ));
    }

    // 1. Resolver-first script resolution under profile policy.
    let mut resolver = ScriptResolver::new(
        effective_profile.script_policy.clone(),
        effective_profile.module_policy.clone(),
        effective_profile.limits.clone(),
    );
    let fail = |kind: NseRunErrorKind, message: String, resolver: &mut ScriptResolver| {
        NseRunError::new(
            kind,
            message,
            &request,
            &effective_profile,
            resolver.take_diagnostics(),
        )
    };

    let resolved_content = match &request.script {
        NseScriptSource::Builtin { name } => {
            // Policy/diag check first; content is the shipped built-in.
            if let Err(e) = resolver.resolve_script(request.script.clone()) {
                return Err(fail(
                    NseRunErrorKind::Resolution,
                    format!(
                        "built-in script resolution failed: {}",
                        load_error_message(&e)
                    ),
                    &mut resolver,
                ));
            }
            let content = crate::get_builtin_script(name);
            enforce_builtin_size(&content, &request, &effective_profile, &mut resolver)?;
            content
        }
        NseScriptSource::File { .. } => match resolver.resolve_script(request.script.clone()) {
            Ok(resolved) => resolved.content,
            Err(e) => {
                // Preserve the historical CLI denial message for profile-gated
                // file sources so manual surfaces keep their UX.
                let message = match &e {
                    NseLoadError::BlockedByPolicy { .. } => format!(
                        "Profile '{}' does not allow arbitrary script files. \
                         Use built-in scripts only.",
                        effective_profile.kind
                    ),
                    _ => format!("script resolution failed: {}", load_error_message(&e)),
                };
                return Err(fail(NseRunErrorKind::Resolution, message, &mut resolver));
            }
        },
        NseScriptSource::TrustedRegistry { .. } | NseScriptSource::InlineManual { .. } => {
            match resolver.resolve_script(request.script.clone()) {
                Ok(resolved) => resolved.content,
                Err(e) => {
                    return Err(fail(
                        NseRunErrorKind::Resolution,
                        format!("script resolution failed: {}", load_error_message(&e)),
                        &mut resolver,
                    ));
                }
            }
        }
    };

    // 2. Executor with the effective profile (never a manual-only default).
    // Per-run host services are threaded at construction so library
    // registration observes the injected bundle; absent injection uses native
    // defaults (existing callers unchanged).
    let host_services = request.effective_host_services();
    let mut executor = match NseExecutor::with_full_policy_and_services(
        effective_profile.sandbox.clone(),
        effective_profile.limits.clone(),
        cancellation.clone(),
        effective_profile.script_policy.clone(),
        effective_profile.module_policy.clone(),
        effective_profile.kind,
        effective_profile.network_policy.clone(),
        host_services,
    ) {
        Ok(executor) => executor,
        Err(e) => {
            return Err(fail(
                NseRunErrorKind::ExecutorInit,
                format!("failed to create NSE executor: {}", e),
                &mut resolver,
            ));
        }
    };

    // 3. Target, script args, and optional host/port context.
    if let Err(e) = executor.set_target(&request.target) {
        return Err(fail(
            NseRunErrorKind::TargetRejected,
            format!("failed to set target: {}", e),
            &mut resolver,
        ));
    }
    if let Some(ref args) = request.script_args {
        if let Err(e) = executor.set_script_args(args) {
            return Err(fail(
                NseRunErrorKind::ScriptArgsRejected,
                format!("invalid script args: {}", e),
                &mut resolver,
            ));
        }
    }
    apply_context(&mut executor, &request, &mut resolver)?;

    // 4. Rule evaluation and action semantics.
    let (output, _raw_outputs, rule_reports) =
        match executor.run_script_with_rules(&resolved_content) {
            Ok(result) => result,
            Err(e) => {
                if cancellation.is_cancelled() {
                    return Err(fail(
                        NseRunErrorKind::Cancelled,
                        format!("execution cancelled: {}", e),
                        &mut resolver,
                    ));
                }
                return Err(fail(
                    NseRunErrorKind::Execution,
                    format!("script execution failed: {}", e),
                    &mut resolver,
                ));
            }
        };
    if cancellation.is_cancelled() {
        return Err(fail(
            NseRunErrorKind::Cancelled,
            "cancellation requested during execution".to_string(),
            &mut resolver,
        ));
    }

    // 5-7. Stats, library-use (dynamic + one static fallback), capability events.
    let stats = executor.execution_stats();
    let mut library_reports = executor.library_reports();
    if library_reports.is_empty() {
        let static_requires = extract_static_requires(&resolved_content);
        if !static_requires.is_empty() {
            library_reports = library_use_reports_from_static_requires(&static_requires);
        }
    }
    let capability_events = executor.capability_events();

    // 8-11. Diagnostics, report, compatibility, evidence — each exactly once.
    let diagnostics = resolver.take_diagnostics();
    let report = NseRunReport::new(&request.target, &script_name)
        .with_profile(&effective_profile)
        .with_script_source(&request.script)
        .with_stats(&stats)
        .with_resolver_diagnostics(&diagnostics)
        .with_libraries(library_reports)
        .with_rules(rule_reports)
        .with_capability_events(capability_events)
        .with_output(&output)
        .compute_compatibility();
    let evidence = extract_evidence(
        &report.target,
        &report.script_name,
        &report.capability_events,
        &report.compatibility,
        &report.rules,
        &report.output,
    );

    // 12. Complete report.
    Ok(report.with_evidence(evidence))
}

/// Enforce script-size policy on shipped built-in content.
///
/// The resolver's built-in path validates policy but does not measure the
/// injected content; apply the same size gates used for file/inline
/// sources so built-ins cannot bypass them.
fn enforce_builtin_size(
    content: &str,
    request: &NseRunRequest,
    effective_profile: &ResolvedNseExecutionProfile,
    resolver: &mut ScriptResolver,
) -> Result<(), NseRunError> {
    let size = content.len();
    let limit = effective_profile
        .limits
        .max_script_bytes
        .or(effective_profile.script_policy.max_script_bytes);
    if let Some(limit) = limit {
        if size > limit {
            let diagnostics = resolver.take_diagnostics();
            let mut error = NseRunError::new(
                NseRunErrorKind::Resolution,
                format!(
                    "built-in script '{}' exceeds size limit ({} > {} bytes)",
                    request.script_name(),
                    size,
                    limit
                ),
                request,
                effective_profile,
                diagnostics,
            );
            error
                .diagnostics
                .push(NseLoadDiagnostic::OversizedRejected {
                    source: request.script.clone(),
                    size,
                    limit,
                });
            return Err(error);
        }
    }
    Ok(())
}

/// Apply optional host/port context to the executor.
///
/// Absent context preserves the executor's synthetic-context behavior;
/// supplied context is injected via the existing host/port setters so rule
/// evaluation observes caller-provided data.
fn apply_context(
    executor: &mut NseExecutor,
    request: &NseRunRequest,
    resolver: &mut ScriptResolver,
) -> Result<(), NseRunError> {
    let fail = |message: String, resolver: &mut ScriptResolver| {
        NseRunError::new(
            NseRunErrorKind::TargetRejected,
            message,
            request,
            &request.profile,
            resolver.take_diagnostics(),
        )
    };

    if let Some(ref host) = request.host_context {
        if let Err(e) = executor.set_host_info(host.hostname.clone(), host.ip.clone(), None, None) {
            tracing::warn!("NSE host context rejected: {}", e);
            return Err(fail(format!("host context rejected: {}", e), resolver));
        }
    }
    if let Some(ref port) = request.port_context {
        let service = port.service.as_ref().and_then(|s| s.name.clone());
        if let Err(e) = executor.add_port(port.port, &port.protocol, &port.state, service) {
            tracing::warn!("NSE port context rejected: {}", e);
            return Err(fail(format!("port context rejected: {}", e), resolver));
        }
    }
    Ok(())
}

/// Render a resolver failure without requiring `Debug` on the error type.
fn load_error_message(e: &NseLoadError) -> String {
    e.to_string()
}