use std::time::SystemTime;
use serde::{Deserialize, Serialize};
use crate::model::exclusion::Exclusions;
use crate::model::ip::scoped::Zone;
use crate::model::ip::set::IpSet;
use crate::model::target::TargetMap;
use crate::model::technique::TcpScanTechnique;
use crate::record::{PlanRecord, wire};
use crate::report::ScanKind;
use crate::system::privilege::Privilege;
#[derive(Debug, Clone)]
pub struct Plan(Resolved);
#[derive(Debug, Clone)]
enum Resolved {
Discovery { addresses: IpSet, sweep: bool },
PortScan {
targets: TargetMap,
technique: TcpScanTechnique,
},
Listen { links: Vec<Zone> },
}
impl Plan {
pub fn discovery(addresses: &IpSet, exclusions: &Exclusions, sweep: bool) -> Self {
let mut addresses = addresses.clone();
exclusions.withhold(&mut addresses);
addresses.canonicalize();
Self(Resolved::Discovery { addresses, sweep })
}
pub fn port_scan(
targets: &TargetMap,
exclusions: &Exclusions,
technique: TcpScanTechnique,
) -> Self {
let mut targets = targets.clone();
exclusions.withhold_targets(&mut targets);
Self(Resolved::PortScan { targets, technique })
}
pub fn listen(links: Vec<Zone>) -> Self {
Self(Resolved::Listen { links })
}
pub fn kind(&self) -> ScanKind {
match self.0 {
Resolved::Discovery { .. } => ScanKind::Discovery,
Resolved::PortScan { .. } => ScanKind::PortScan,
Resolved::Listen { .. } => ScanKind::Listen,
}
}
pub fn links(&self) -> Option<&[Zone]> {
match &self.0 {
Resolved::Listen { links } => Some(links),
_ => None,
}
}
pub fn total_targets(&self) -> u128 {
match &self.0 {
Resolved::Discovery { addresses, .. } => addresses.len(),
Resolved::PortScan { targets, .. } => targets.gross_targets().unwrap_or_default(),
Resolved::Listen { .. } => 0,
}
}
pub fn addresses(&self) -> Option<&IpSet> {
match &self.0 {
Resolved::Discovery { addresses, .. } => Some(addresses),
Resolved::PortScan { .. } | Resolved::Listen { .. } => None,
}
}
pub fn targets(&self) -> Option<&TargetMap> {
match &self.0 {
Resolved::PortScan { targets, .. } => Some(targets),
Resolved::Discovery { .. } | Resolved::Listen { .. } => None,
}
}
pub fn technique(&self) -> Option<TcpScanTechnique> {
match &self.0 {
Resolved::PortScan { technique, .. } => Some(*technique),
Resolved::Discovery { .. } | Resolved::Listen { .. } => None,
}
}
pub fn sweeps_the_segment(&self) -> bool {
matches!(self.0, Resolved::Discovery { sweep: true, .. })
}
pub fn record(&self) -> PlanRecord {
match &self.0 {
Resolved::Discovery { addresses, .. } => PlanRecord::from(addresses),
Resolved::PortScan { targets, .. } => PlanRecord::from(targets),
Resolved::Listen { .. } => PlanRecord::default(),
}
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
pub struct PlanFingerprint(u64);
impl PlanFingerprint {
pub fn of(plan: &Plan, privilege: Privilege) -> Self {
let mut digest = Digest::new();
digest.text(wire::scan_kind_name(plan.kind()));
match &plan.0 {
Resolved::Discovery { addresses, sweep } => {
digest.flag(privilege.is_raw());
digest.flag(*sweep);
digest.addresses(addresses);
}
Resolved::Listen { links } => {
digest.count(links.len());
for link in links {
digest.text(link.name());
}
}
Resolved::PortScan { targets, technique } => {
digest.flag(privilege.is_raw());
digest.text(technique.name());
digest.count(targets.units.len());
for unit in &targets.units {
digest.addresses(unit.ips());
let ports = unit.ports().to_vec();
digest.count(ports.len());
for (port, protocol) in ports {
digest.number(u64::from(port));
digest.text(wire::protocol_name(protocol));
}
}
}
}
digest.wide(plan.total_targets());
Self(digest.finish())
}
}
struct Digest(u64);
impl Digest {
const BASIS: u64 = 0xcbf2_9ce4_8422_2325;
const PRIME: u64 = 0x0000_0100_0000_01b3;
fn new() -> Self {
Self(Self::BASIS)
}
fn bytes(&mut self, bytes: &[u8]) {
for byte in bytes {
self.0 ^= u64::from(*byte);
self.0 = self.0.wrapping_mul(Self::PRIME);
}
}
fn text(&mut self, text: &str) {
self.number(text.len() as u64);
self.bytes(text.as_bytes());
}
fn number(&mut self, value: u64) {
self.bytes(&value.to_le_bytes());
}
fn wide(&mut self, value: u128) {
self.bytes(&value.to_le_bytes());
}
fn count(&mut self, value: usize) {
self.number(value as u64);
}
fn flag(&mut self, value: bool) {
self.bytes(&[u8::from(value)]);
}
fn addresses(&mut self, ips: &IpSet) {
self.count(ips.v4().len());
for range in ips.v4() {
self.bytes(&[4]);
self.bytes(&range.start_addr().octets());
self.bytes(&range.end_addr().octets());
}
self.count(ips.v6().len());
for range in ips.v6() {
self.bytes(&[6]);
self.bytes(&range.start_addr().octets());
self.bytes(&range.end_addr().octets());
match range.zone() {
Some(zone) => {
self.bytes(&[1]);
self.number(u64::from(zone));
}
None => self.bytes(&[0]),
}
}
}
fn finish(self) -> u64 {
self.0
}
}
#[non_exhaustive]
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct JournalManifest {
pub journal_version: u32,
pub id: String,
pub engine_version: String,
pub created_at: SystemTime,
#[serde(default)]
pub kind: String,
pub plan: PlanFingerprint,
#[serde(default)]
pub targets: PlanRecord,
#[serde(default)]
pub technique: String,
#[serde(default)]
pub sweep: bool,
#[serde(default)]
pub links: Vec<String>,
#[serde(
rename = "privileged",
default = "wire_privilege::unrecorded",
with = "wire_privilege"
)]
pub privilege: Privilege,
pub total_targets: u128,
#[serde(default)]
pub order_seed: Option<u64>,
pub summary: String,
}
mod wire_privilege {
use serde::{Deserialize, Deserializer, Serialize, Serializer};
use crate::system::privilege::Privilege;
pub(super) fn unrecorded() -> Privilege {
Privilege::Connect
}
pub(super) fn serialize<S: Serializer>(
privilege: &Privilege,
serializer: S,
) -> Result<S::Ok, S::Error> {
privilege.is_raw().serialize(serializer)
}
pub(super) fn deserialize<'de, D: Deserializer<'de>>(
deserializer: D,
) -> Result<Privilege, D::Error> {
Ok(if bool::deserialize(deserializer)? {
Privilege::Raw
} else {
Privilege::Connect
})
}
}
impl JournalManifest {
pub fn new(
id: impl Into<String>,
plan: &Plan,
privilege: Privilege,
summary: impl Into<String>,
) -> Self {
Self {
journal_version: super::JOURNAL_VERSION,
id: id.into(),
engine_version: env!("CARGO_PKG_VERSION").to_string(),
created_at: SystemTime::now(),
kind: wire::scan_kind_name(plan.kind()).to_owned(),
plan: PlanFingerprint::of(plan, privilege),
targets: plan.record(),
technique: plan
.technique()
.map(|technique| technique.name().to_owned())
.unwrap_or_default(),
sweep: plan.sweeps_the_segment(),
links: plan
.links()
.unwrap_or_default()
.iter()
.map(|link| link.name().to_owned())
.collect(),
privilege,
total_targets: plan.total_targets(),
order_seed: Some(rand::random()),
summary: summary.into(),
}
}
pub fn kind(&self) -> ScanKind {
wire::scan_kind(&self.kind).unwrap_or(ScanKind::PortScan)
}
pub fn recorded(&self) -> Plan {
Plan(match self.kind() {
ScanKind::Discovery => Resolved::Discovery {
addresses: self.targets.addresses(),
sweep: self.sweep,
},
ScanKind::Listen => Resolved::Listen {
links: self
.links
.iter()
.map(|name| Zone::unresolved(name.as_str()))
.collect(),
},
ScanKind::PortScan => Resolved::PortScan {
targets: TargetMap::from(&self.targets),
technique: self.technique(),
},
})
}
pub fn technique(&self) -> TcpScanTechnique {
self.technique.parse().unwrap_or_default()
}
pub fn covers(&self, plan: &Plan, privilege: Privilege) -> Result<(), PlanChanged> {
let found = PlanFingerprint::of(plan, privilege);
if found == self.plan {
return Ok(());
}
Err(PlanChanged {
expected: self.plan,
found,
expected_targets: self.total_targets,
found_targets: plan.total_targets(),
})
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct PlanChanged {
pub expected: PlanFingerprint,
pub found: PlanFingerprint,
pub expected_targets: u128,
pub found_targets: u128,
}
impl std::fmt::Display for PlanChanged {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
write!(
f,
"this journal was written against a different plan, so its recorded \
positions would name different targets"
)?;
if self.expected_targets != self.found_targets {
write!(
f,
" ({} targets then, {} now)",
self.expected_targets, self.found_targets
)?;
} else {
write!(
f,
" (the same {} targets, differently arranged, or a different \
technique or privilege level)",
self.expected_targets
)?;
}
Ok(())
}
}
impl std::error::Error for PlanChanged {}
#[cfg(test)]
mod tests {
use super::*;
use crate::model::ip::set::IpSet;
use crate::model::port::PortSet;
use crate::model::target::TargetSet;
fn plan(pairs: &[(&str, &str)]) -> TargetMap {
let mut map = TargetMap::new();
for (range, ports) in pairs {
map.add_unit(TargetSet::new(
range.parse::<IpSet>().expect("a range"),
ports.parse::<PortSet>().expect("ports"),
));
}
map
}
fn ports(map: &TargetMap) -> Plan {
Plan::port_scan(map, &Exclusions::none(), TcpScanTechnique::Syn)
}
fn print(map: &TargetMap) -> PlanFingerprint {
PlanFingerprint::of(&ports(map), Privilege::Raw)
}
fn addresses(written: &str) -> IpSet {
written.parse().expect("a range")
}
fn sweeping(ips: &IpSet, sweep: bool) -> Plan {
Plan::discovery(ips, &Exclusions::none(), sweep)
}
#[test]
fn the_derivation_is_pinned_to_a_value() {
assert_eq!(
print(&plan(&[("192.0.2.1-192.0.2.10", "80,443")])).0,
0xa4d1_e087_ea5b_98c2,
"the plan fingerprint derivation has moved"
);
}
#[test]
fn the_same_plan_fingerprints_the_same() {
let a = plan(&[("192.0.2.1-192.0.2.10", "80,443")]);
let b = plan(&[("192.0.2.1-192.0.2.10", "80,443")]);
assert_eq!(print(&a), print(&a), "not stable within one value");
assert_eq!(print(&a), print(&b), "not stable across equal values");
}
#[test]
fn any_change_that_renumbers_targets_changes_the_fingerprint() {
let base = plan(&[("192.0.2.1-192.0.2.10", "80,443")]);
let original = print(&base);
for (what, changed) in [
(
"a port added",
plan(&[("192.0.2.1-192.0.2.10", "80,443,8080")]),
),
("a port removed", plan(&[("192.0.2.1-192.0.2.10", "80")])),
(
"the range widened",
plan(&[("192.0.2.1-192.0.2.20", "80,443")]),
),
(
"the range narrowed",
plan(&[("192.0.2.1-192.0.2.5", "80,443")]),
),
(
"a unit added",
plan(&[("192.0.2.1-192.0.2.10", "80,443"), ("198.51.100.1", "22")]),
),
] {
assert_ne!(
original,
print(&changed),
"{what} left the fingerprint alone"
);
}
}
#[test]
fn the_order_of_the_ports_is_part_of_the_plan() {
let ascending = plan(&[("192.0.2.1", "80,443")]);
let descending = plan(&[("192.0.2.1", "443,80")]);
let same_order =
ascending.units[0].ports().to_vec() == descending.units[0].ports().to_vec();
assert_eq!(
print(&ascending) == print(&descending),
same_order,
"the fingerprint must follow the enumeration, whichever way the set orders it"
);
}
#[test]
fn the_shape_of_the_units_is_not_flattened_away() {
let split = plan(&[
("192.0.2.1-192.0.2.5", "80"),
("192.0.2.6-192.0.2.10", "80"),
]);
let joined = plan(&[("192.0.2.1-192.0.2.10", "80")]);
assert_eq!(
split.gross_targets().unwrap(),
joined.gross_targets().unwrap(),
"the same ten targets either way, which is what makes this the trap"
);
assert_ne!(
print(&split),
print(&joined),
"two units enumerate differently from one"
);
}
#[test]
fn privilege_and_technique_are_part_of_the_plan() {
let map = plan(&[("192.0.2.1-192.0.2.10", "80,443")]);
assert_ne!(
PlanFingerprint::of(&ports(&map), Privilege::Raw),
PlanFingerprint::of(&ports(&map), Privilege::Connect),
"privilege decides which question the probes answered"
);
assert_ne!(
PlanFingerprint::of(&ports(&map), Privilege::Raw),
PlanFingerprint::of(
&Plan::port_scan(&map, &Exclusions::none(), TcpScanTechnique::Fin),
Privilege::Raw
),
"a technique decides what silence means"
);
}
#[cfg(feature = "journal-format")]
#[test]
fn privilege_is_written_as_the_boolean_the_format_promised() {
let map = plan(&[("192.0.2.1", "80")]);
let manifest = JournalManifest::new("01J8Z5Q7VN", &ports(&map), Privilege::Raw, "");
let mut written = serde_json::to_value(&manifest).expect("a manifest serializes");
assert_eq!(written["privileged"], serde_json::Value::Bool(true));
let read: JournalManifest =
serde_json::from_value(written.clone()).expect("and reads back");
assert_eq!(read.privilege, Privilege::Raw);
assert_eq!(read.plan, manifest.plan, "the same plan, still");
written["privileged"] = serde_json::Value::Bool(false);
let read: JournalManifest = serde_json::from_value(written).expect("a connect scan reads");
assert_eq!(read.privilege, Privilege::Connect, "the polarity is intact");
}
#[cfg(feature = "journal-format")]
#[test]
fn a_manifest_that_records_no_order_asks_for_none() {
let map = plan(&[("192.0.2.1", "80")]);
let manifest = JournalManifest::new("01J8Z5Q7VN", &ports(&map), Privilege::Raw, "");
assert!(manifest.order_seed.is_some(), "a fresh journal draws one");
let mut written = serde_json::to_value(&manifest).expect("a manifest serializes");
let read: JournalManifest =
serde_json::from_value(written.clone()).expect("and reads back");
assert_eq!(read.order_seed, manifest.order_seed);
written
.as_object_mut()
.expect("an object")
.remove("order_seed");
let read: JournalManifest =
serde_json::from_value(written).expect("an older journal reads");
assert_eq!(read.order_seed, None);
}
#[cfg(feature = "journal-format")]
#[test]
fn two_journals_of_one_plan_ask_about_it_differently() {
let map = plan(&[("192.0.2.0/24", "1-1024")]);
let one = JournalManifest::new("01J8Z5Q7VN", &ports(&map), Privilege::Raw, "");
let other = JournalManifest::new("01J8Z5Q7VP", &ports(&map), Privilege::Raw, "");
assert_eq!(one.plan, other.plan, "the same plan");
assert_ne!(one.order_seed, other.order_seed, "asked in its own order");
}
#[cfg(feature = "journal-format")]
#[test]
fn a_manifest_that_records_no_privilege_reads_as_a_connect_scan() {
let map = plan(&[("192.0.2.1", "80")]);
let manifest = JournalManifest::new("01J8Z5Q7VN", &ports(&map), Privilege::Raw, "");
let mut written = serde_json::to_value(&manifest).expect("a manifest serializes");
written
.as_object_mut()
.expect("an object")
.remove("privileged");
let read: JournalManifest = serde_json::from_value(written).expect("an older manifest");
assert_eq!(read.privilege, Privilege::Connect);
}
#[test]
fn a_manifest_covers_its_own_plan_and_refuses_another() {
let original = plan(&[("192.0.2.1-192.0.2.10", "80,443")]);
let manifest = JournalManifest::new(
"01J8Z5Q7VN",
&ports(&original),
Privilege::Raw,
"192.0.2.1-192.0.2.10 on 2 ports",
);
assert_eq!(manifest.total_targets, 20);
assert_eq!(manifest.kind(), ScanKind::PortScan);
assert!(manifest.covers(&ports(&original), Privilege::Raw).is_ok());
let widened = plan(&[("192.0.2.1-192.0.2.20", "80,443")]);
let refused = manifest
.covers(&ports(&widened), Privilege::Raw)
.expect_err("a widened plan renumbers every position past the first host");
assert_eq!(refused.expected_targets, 20);
assert_eq!(refused.found_targets, 40);
assert!(
refused.to_string().contains("20 targets then, 40 now"),
"{refused}"
);
}
#[test]
fn a_sweep_is_never_the_same_plan_as_a_port_scan() {
let ips = addresses("192.0.2.1-192.0.2.10");
let map = plan(&[("192.0.2.1-192.0.2.10", "80")]);
assert_ne!(
PlanFingerprint::of(&sweeping(&ips, false), Privilege::Raw),
print(&map),
"the same ten addresses, asked two different questions"
);
let manifest =
JournalManifest::new("01J8Z5Q7VN", &sweeping(&ips, false), Privilege::Raw, "");
assert_eq!(manifest.kind(), ScanKind::Discovery);
assert_eq!(manifest.total_targets, 10, "a sweep counts addresses");
assert!(
manifest.covers(&ports(&map), Privilege::Raw).is_err(),
"a sweep's journal must not accept a port scan's plan"
);
}
#[test]
fn a_segment_sweep_is_not_a_targeted_pass() {
let ips = addresses("192.0.2.1-192.0.2.10");
assert_ne!(
PlanFingerprint::of(&sweeping(&ips, true), Privilege::Raw),
PlanFingerprint::of(&sweeping(&ips, false), Privilege::Raw)
);
}
#[test]
fn a_sweeps_addresses_survive_the_round_trip() {
let ips = addresses("192.0.2.1-192.0.2.10,2001:db8::1");
let manifest =
JournalManifest::new("01J8Z5Q7VN", &sweeping(&ips, false), Privilege::Raw, "");
assert_eq!(
manifest.recorded().addresses().map(IpSet::len),
Some(ips.len())
);
assert!(
manifest
.covers(
&sweeping(
&manifest.recorded().addresses().cloned().unwrap_or_default(),
false
),
Privilege::Raw
)
.is_ok(),
"a plan rebuilt from the record must fingerprint as the original"
);
}
#[test]
fn a_link_local_plan_comes_back_in_the_order_it_was_counted() {
let mut ips = IpSet::new();
for (zone, last) in [(9u32, 4u16), (3, 6), (7, 2)] {
ips.insert_range(crate::model::ip::range::IpRange::V6(
crate::model::ip::range::Ipv6Range::scoped(
"fe80::1".parse().expect("an address"),
format!("fe80::{last}").parse().expect("an address"),
Some(zone),
)
.expect("a range"),
));
}
ips.canonicalize();
let manifest =
JournalManifest::new("01J8Z5Q7VN", &sweeping(&ips, false), Privilege::Raw, "");
let recovered = manifest
.recorded()
.addresses()
.cloned()
.expect("a sweep's plan");
assert_eq!(
recovered.iter().collect::<Vec<_>>(),
ips.iter().collect::<Vec<_>>(),
"the same addresses in the same order, so positions still mean what they did"
);
assert!(
manifest
.covers(&sweeping(&recovered, false), Privilege::Raw)
.is_ok(),
"and the plan rebuilt from the record fingerprints as the original"
);
}
#[test]
fn a_refusal_over_an_equal_count_says_so_rather_than_reporting_a_change() {
let map = plan(&[("192.0.2.1-192.0.2.10", "80,443")]);
let manifest = JournalManifest::new("01J8Z5Q7VN", &ports(&map), Privilege::Raw, "");
let refused = manifest
.covers(
&Plan::port_scan(&map, &Exclusions::none(), TcpScanTechnique::Fin),
Privilege::Raw,
)
.expect_err("a different technique is a different plan");
assert_eq!(refused.expected_targets, refused.found_targets);
let message = refused.to_string();
assert!(message.contains("differently arranged"), "{message}");
assert!(!message.contains("then,"), "{message}");
}
#[test]
fn a_watch_never_shares_a_fingerprint_with_a_phase_that_walks_targets() {
let listen = Plan::listen(vec![Zone::unresolved("en0")]);
let mut ips = IpSet::new();
ips.insert_range("192.0.2.0/24".parse().expect("a valid range"));
assert_ne!(
PlanFingerprint::of(&listen, Privilege::Raw),
PlanFingerprint::of(&sweeping(&ips, true), Privilege::Raw),
);
assert_eq!(listen.kind(), ScanKind::Listen);
assert_eq!(
listen.total_targets(),
0,
"not `none were found`: there is no unit a watch is counted in"
);
}
#[test]
fn a_watch_of_another_link_is_another_job() {
let one = Plan::listen(vec![Zone::unresolved("en0")]);
let other = Plan::listen(vec![Zone::unresolved("en1")]);
let both = Plan::listen(vec![Zone::unresolved("en0"), Zone::unresolved("en1")]);
assert_ne!(
PlanFingerprint::of(&one, Privilege::Raw),
PlanFingerprint::of(&other, Privilege::Raw),
);
assert_ne!(
PlanFingerprint::of(&one, Privilege::Raw),
PlanFingerprint::of(&both, Privilege::Raw),
);
}
#[test]
fn privilege_decides_a_probing_plan_and_says_nothing_about_a_watch() {
let watch = Plan::listen(vec![Zone::unresolved("en0")]);
assert_eq!(
PlanFingerprint::of(&watch, Privilege::Connect),
PlanFingerprint::of(&watch, Privilege::Raw),
"a watch under sudo is the same watch"
);
let ips = addresses("192.0.2.0/30");
assert_ne!(
PlanFingerprint::of(&sweeping(&ips, false), Privilege::Connect),
PlanFingerprint::of(&sweeping(&ips, false), Privilege::Raw),
"a sweep's probes are not the same probes"
);
let map = plan(&[("192.0.2.1-192.0.2.10", "80,443")]);
assert_ne!(
PlanFingerprint::of(&ports(&map), Privilege::Connect),
PlanFingerprint::of(&ports(&map), Privilege::Raw),
"and neither are a port scan's"
);
}
#[test]
fn a_link_is_the_same_link_whatever_number_the_kernel_gave_it_today() {
let before = Plan::listen(vec![Zone::new(3, "en0")]);
let after = Plan::listen(vec![Zone::new(11, "en0")]);
assert_eq!(
PlanFingerprint::of(&before, Privilege::Raw),
PlanFingerprint::of(&after, Privilege::Raw),
);
}
#[test]
fn a_watch_reads_back_as_the_links_it_was_written_with() {
let plan = Plan::listen(vec![Zone::new(3, "en0"), Zone::new(4, "en1")]);
let manifest = JournalManifest::new("id", &plan, Privilege::Raw, "listening");
let recorded = manifest.recorded();
assert_eq!(recorded.kind(), ScanKind::Listen);
assert_eq!(
recorded
.links()
.expect("a watch names links")
.iter()
.map(|link| link.name().to_owned())
.collect::<Vec<_>>(),
vec!["en0".to_owned(), "en1".to_owned()],
);
manifest
.covers(&plan, Privilege::Raw)
.expect("the plan it was written against still covers it");
}
}