pub mod model;
pub mod os;
mod analyzer;
mod db;
mod extract;
mod http;
mod matcher;
mod pattern;
mod prefilter;
mod response;
mod signature;
mod snmp;
mod ssh;
mod tls;
mod tls_cert;
mod tls_summary;
#[cfg(test)]
mod corpus;
#[cfg(test)]
mod pattern_properties;
pub use analyzer::{Analyzer, BannerRegexAnalyzer, PortContext};
pub use db::SignatureDb;
pub use http::HttpHeadersAnalyzer;
pub use model::{Confidence, Evidence, ServiceVerdict, SourceId, Tunnel};
pub use response::{Collected, ResponseSet, TlsInfo};
pub use signature::{
MAX_COMPILED_REGEX_BYTES, MAX_UDP_PROBE_BYTES, MatchRule, Probe, ServiceDefinition,
ServiceSignature,
};
pub use ssh::SshAnalyzer;
pub use tls_cert::TlsCertAnalyzer;
use std::net::SocketAddr;
use std::time::Duration;
use tokio::io::{AsyncRead, AsyncReadExt, AsyncWrite, AsyncWriteExt};
use tokio::net::TcpStream;
use tokio::time::timeout;
use crate::config::ServiceDetection;
use crate::model::port::{Port, PortState, Protocol, Service};
const BANNER_READ_TIMEOUT: Duration = Duration::from_millis(500);
const PROBE_READ_TIMEOUT: Duration = Duration::from_millis(1_000);
const CONTINUATION_GRACE: Duration = Duration::from_millis(50);
const USER_AGENT: &str = "ZondScanner/1.0";
const CONNECT_RETRY_TIMEOUT: Duration = Duration::from_millis(500);
const MAX_RESPONSE_BYTES: usize = 4096;
#[must_use]
pub fn reads_replies(port: u16, protocol: Protocol) -> bool {
extract::reads(port, protocol)
}
pub fn lookup_service_name(port: u16, _protocol: Protocol) -> Option<String> {
SignatureDb::global()
.service_name(port)
.map(|s| s.to_string())
}
pub fn baseline_service(port: u16, protocol: Protocol) -> Option<Service> {
lookup_service_name(port, protocol).map(|name| Service::new(name, 0))
}
pub fn baseline_port(port: u16, protocol: Protocol, state: PortState) -> Port {
let mut classified = Port::new(port, protocol, state);
if let Some(service) = baseline_service(port, protocol) {
classified.set_service(service);
}
classified
}
pub async fn fingerprint_tcp(stream: TcpStream, port: Port, detection: ServiceDetection) -> Port {
fingerprint_tcp_detailed(stream, port, detection).await.0
}
pub async fn fingerprint_tcp_detailed(
stream: TcpStream,
mut port: Port,
detection: ServiceDetection,
) -> (Port, Vec<os::OsEvidence>) {
let addr = stream.peer_addr().ok();
let (responses, tunnel) = gather(stream, port.number(), detection).await;
if responses.is_empty() {
return (port, Vec::new());
}
if let Some(tls) = responses.tls.as_ref() {
port.set_security(tls_summary::security(tls));
}
let fallback = first_printable(&responses.banners);
let mut about_the_host = Vec::new();
match analyze(port.number(), Protocol::Tcp, addr, responses, tunnel).await {
Some(verdict) if !verdict.is_empty() => {
about_the_host.extend(verdict.evidence.iter().filter_map(|e| e.os.clone()));
if let Some(service) = verdict.to_service() {
port.set_service(service);
}
}
_ => {
if let Some(banner) = fallback {
port.set_service(Service::new(format!("banner: {banner}"), 0));
}
}
}
(port, about_the_host)
}
pub async fn fingerprint_udp_detailed(
addr: std::net::SocketAddr,
mut port: Port,
) -> Option<(Port, Vec<os::OsEvidence>)> {
let text = probe_udp(addr).await?;
let responses = ResponseSet::from_banners(vec![text]);
let verdict = analyze(addr.port(), Protocol::Udp, None, responses, None)
.await
.filter(|verdict| !verdict.is_empty())?;
let about_the_host = verdict
.evidence
.iter()
.filter_map(|e| e.os.clone())
.collect();
if let Some(service) = verdict.to_service() {
port.set_service(service);
}
Some((port, about_the_host))
}
async fn probe_udp(addr: std::net::SocketAddr) -> Option<String> {
let payload = SignatureDb::global()
.udp_probe_payloads(addr.port())
.first()?;
let bind = if addr.is_ipv4() {
"0.0.0.0:0"
} else {
"[::]:0"
};
let socket = tokio::net::UdpSocket::bind(bind).await.ok()?;
socket.connect(addr).await.ok()?;
socket.send(payload).await.ok()?;
let mut buffer = vec![0u8; MAX_RESPONSE_BYTES];
let read = timeout(PROBE_READ_TIMEOUT, socket.recv(&mut buffer))
.await
.ok()?
.ok()?;
extract::from_datagram(addr.port(), &buffer[..read])
}
async fn gather(
mut stream: TcpStream,
port: u16,
detection: ServiceDetection,
) -> (ResponseSet, Option<Tunnel>) {
let peer = stream.peer_addr().ok().map(|addr| addr.ip());
let socket = stream.peer_addr().ok();
if !detection.connects() {
return (ResponseSet::default(), None);
}
if !detection.sends() {
let banner = read_response(&mut stream, BANNER_READ_TIMEOUT).await;
return (
ResponseSet::from_banners(banner.into_iter().collect()),
None,
);
}
if tls::is_tls_port(port) {
return match peer {
Some(ip) => tunneled(tls::handshake(stream, ip).await, port).await,
None => (ResponseSet::default(), None),
};
}
let probes = SignatureDb::global().tcp_probe_payloads(port);
if !probes.is_empty() {
let banners = collect_responses(&mut stream, probes).await;
return (ResponseSet::from_banners(banners), None);
}
match ask_generically(&mut stream, socket).await {
GenericReply::Spoke(banners) => (ResponseSet::from_banners(banners), None),
GenericReply::Tls | GenericReply::Silent => match (peer, socket) {
(Some(ip), Some(socket)) => {
let Ok(Ok(fresh)) =
timeout(CONNECT_RETRY_TIMEOUT, TcpStream::connect(socket)).await
else {
return (ResponseSet::default(), None);
};
tunneled(tls::speculative_handshake(fresh, ip).await, port).await
}
_ => (ResponseSet::default(), None),
},
}
}
enum GenericReply {
Spoke(Vec<String>),
Tls,
Silent,
}
async fn ask_generically(stream: &mut TcpStream, socket: Option<SocketAddr>) -> GenericReply {
for payload in SignatureDb::global().generic_tcp_probe_payloads() {
if stream.write_all(payload).await.is_err() {
break;
}
}
let Some(bytes) = read_bytes(stream, PROBE_READ_TIMEOUT, CONTINUATION_GRACE).await else {
return GenericReply::Silent;
};
if looks_like_tls(&bytes) {
return GenericReply::Tls;
}
let first = String::from_utf8_lossy(&bytes).into_owned();
let followed = match (socket, redirect_path(&first)) {
(Some(socket), Some(path)) => follow_redirect(socket, &path).await,
_ => None,
};
GenericReply::Spoke(std::iter::once(first).chain(followed).collect())
}
fn redirect_path(response: &str) -> Option<String> {
let (status, headers) = response.split_once("\r\n").or(response.split_once('\n'))?;
let code: u16 = status.split_whitespace().nth(1)?.parse().ok()?;
if !(300..400).contains(&code) {
return None;
}
let location = headers
.lines()
.take_while(|line| !line.trim_end_matches('\r').is_empty())
.find_map(|line| {
let (name, value) = line.split_once(':')?;
name.trim()
.eq_ignore_ascii_case("location")
.then(|| value.trim())
})?;
match location {
path if path.starts_with('/') => Some(path.to_string()),
_ => None,
}
}
async fn follow_redirect(socket: SocketAddr, path: &str) -> Option<String> {
let mut stream = timeout(CONNECT_RETRY_TIMEOUT, TcpStream::connect(socket))
.await
.ok()?
.ok()?;
let request = format!(
"GET {path} HTTP/1.1\r\nHost: {}\r\nUser-Agent: {USER_AGENT}\r\n\
Accept: */*\r\nConnection: close\r\n\r\n",
socket.ip()
);
stream.write_all(request.as_bytes()).await.ok()?;
read_document(&mut stream, PROBE_READ_TIMEOUT).await
}
fn looks_like_tls(bytes: &[u8]) -> bool {
matches!(bytes, [0x14..=0x17, 0x03, 0x00..=0x04, ..])
}
async fn tunneled(
handshake: Option<(tls::TlsTunnel, TlsInfo)>,
port: u16,
) -> (ResponseSet, Option<Tunnel>) {
let Some((mut tunnel, info)) = handshake else {
return (ResponseSet::default(), None);
};
let db = SignatureDb::global();
let probes = match db.tcp_probe_payloads(port) {
[] => db.generic_tcp_probe_payloads(),
own => own,
};
let banners = collect_responses(&mut tunnel, probes).await;
let responses = ResponseSet {
banners,
tls: Some(info),
};
(responses, Some(Tunnel::Tls))
}
async fn collect_responses<S>(stream: &mut S, probes: &[Vec<u8>]) -> Vec<String>
where
S: AsyncRead + AsyncWrite + Unpin,
{
let mut banners = Vec::new();
if let Some(banner) = read_response(stream, BANNER_READ_TIMEOUT).await {
banners.push(banner);
}
for payload in probes {
if stream.write_all(payload).await.is_err() {
break;
}
if let Some(reply) = read_document(stream, PROBE_READ_TIMEOUT).await {
banners.push(reply);
}
}
banners
}
static ANALYZERS: &[&dyn Analyzer] = &[
&BannerRegexAnalyzer,
&HttpHeadersAnalyzer,
&SshAnalyzer,
&TlsCertAnalyzer,
];
async fn analyze(
port: u16,
protocol: Protocol,
addr: Option<std::net::SocketAddr>,
responses: ResponseSet,
tunnel: Option<Tunnel>,
) -> Option<ServiceVerdict> {
let ctx = PortContext {
port,
protocol,
addr,
tunnel,
};
let mut collected = Vec::with_capacity(ANALYZERS.len());
for analyzer in ANALYZERS {
collected.push(if analyzer.interested(&ctx) {
analyzer.collect(&ctx).await
} else {
Collected::default()
});
}
tokio::task::spawn_blocking(move || {
let mut evidence = Vec::new();
for (analyzer, collected) in ANALYZERS.iter().zip(&collected) {
if analyzer.interested(&ctx) {
evidence.extend(analyzer.analyze(&ctx, &responses, collected));
}
}
(!evidence.is_empty()).then(|| ServiceVerdict::resolve(evidence))
})
.await
.ok()
.flatten()
}
async fn read_response<S>(stream: &mut S, wait: Duration) -> Option<String>
where
S: AsyncRead + Unpin,
{
read_bytes(stream, wait, Duration::ZERO)
.await
.map(|bytes| String::from_utf8_lossy(&bytes).into_owned())
}
async fn read_document<S>(stream: &mut S, wait: Duration) -> Option<String>
where
S: AsyncRead + Unpin,
{
read_bytes(stream, wait, CONTINUATION_GRACE)
.await
.map(|bytes| String::from_utf8_lossy(&bytes).into_owned())
}
async fn read_bytes<S>(stream: &mut S, wait: Duration, grace: Duration) -> Option<Vec<u8>>
where
S: AsyncRead + Unpin,
{
let mut collected: Vec<u8> = Vec::new();
let mut buffer = [0u8; MAX_RESPONSE_BYTES];
let mut budget = wait;
while collected.len() < MAX_RESPONSE_BYTES {
match timeout(budget, stream.read(&mut buffer)).await {
Ok(Ok(n)) if n > 0 => {
let room = MAX_RESPONSE_BYTES - collected.len();
collected.extend_from_slice(&buffer[..n.min(room)]);
if grace.is_zero() {
break;
}
budget = grace;
}
_ => break,
}
}
(!collected.is_empty()).then_some(collected)
}
fn first_printable(responses: &[String]) -> Option<String> {
let printable: String = responses
.iter()
.flat_map(|response| response.chars())
.filter(|c| c.is_ascii_graphic() || *c == ' ')
.take(32)
.collect();
(!printable.is_empty()).then_some(printable)
}
#[cfg(test)]
mod tests {
#[test]
fn an_unregistered_port_is_seeded_with_nothing() {
use crate::model::port::Protocol;
assert!(baseline_service(22, Protocol::Tcp).is_some());
let unregistered = (40_000..=65_535)
.find(|port| lookup_service_name(*port, Protocol::Tcp).is_none())
.expect("some port in the ephemeral range is unregistered");
assert!(
baseline_service(unregistered, Protocol::Tcp).is_none(),
"port {unregistered} invented a service name"
);
assert!(
baseline_port(unregistered, Protocol::Tcp, PortState::Closed)
.service()
.is_none()
);
}
#[test]
fn a_seeded_label_is_never_mistaken_for_an_identification() {
use crate::model::port::Protocol;
let seeded = baseline_service(22, Protocol::Tcp).expect("ssh is registered");
assert_eq!(seeded.name(), "ssh");
assert!(
seeded.is_inferred(),
"nothing asked port 22 what it was running"
);
}
#[test]
fn a_same_host_redirect_names_where_to_look_next() {
let jellyfin = "HTTP/1.1 302 Found\r\n\
Location: /web/index.html\r\n\
Server: Kestrel\r\n\r\n";
assert_eq!(redirect_path(jellyfin).as_deref(), Some("/web/index.html"));
}
#[test]
fn a_redirect_off_the_host_is_declined() {
for location in [
"https://example.com/login",
"http://somewhere.else/",
"https://127.0.0.1/web/",
] {
let response = format!("HTTP/1.1 302 Found\r\nLocation: {location}\r\n\r\n");
assert_eq!(
redirect_path(&response),
None,
"`{location}` is not somewhere this scan may follow"
);
}
}
#[test]
fn a_response_that_is_not_a_redirect_names_nowhere_to_go() {
assert_eq!(
redirect_path("HTTP/1.1 200 OK\r\nLocation: /ignored\r\n\r\n"),
None,
"a 200 is an answer, whatever else it carries"
);
assert_eq!(
redirect_path("HTTP/1.1 302 Found\r\nServer: nginx\r\n\r\n"),
None,
"and a redirect naming nowhere leads nowhere"
);
assert_eq!(redirect_path("SSH-2.0-OpenSSH_9.2p1\r\n"), None);
assert_eq!(redirect_path(""), None);
}
#[test]
fn a_tls_alert_is_recognised_as_tls_rather_than_as_a_banner() {
assert!(looks_like_tls(&[0x15, 0x03, 0x03, 0x00, 0x02, 0x02, 0x0A]));
assert!(looks_like_tls(&[0x16, 0x03, 0x01, 0x00, 0x2A]));
assert!(!looks_like_tls(b"HTTP/1.1 200 OK"));
assert!(!looks_like_tls(b"SSH-2.0-OpenSSH_9.2p1"));
assert!(!looks_like_tls(&[0x15]), "too short to be a record");
assert!(!looks_like_tls(&[]));
}
use super::*;
#[tokio::test]
async fn analyze_runs_both_phases_and_resolves() {
let responses = ResponseSet::from_banners(vec!["SSH-2.0-OpenSSH_9.6p1 Debian".to_string()]);
let verdict = analyze(22, Protocol::Tcp, None, responses, None)
.await
.expect("names a service");
assert_eq!(verdict.service.as_deref(), Some("ssh"));
assert_eq!(verdict.product.as_deref(), Some("OpenSSH"));
assert_eq!(verdict.version.as_deref(), Some("9.6p1"));
}
#[tokio::test]
async fn analyze_identifies_a_long_tail_http_server_end_to_end() {
let responses = ResponseSet::from_banners(vec![
"HTTP/1.1 200 OK\r\nServer: gunicorn/21.2.0\r\nContent-Type: text/html\r\n\r\n"
.to_string(),
]);
let verdict = analyze(8000, Protocol::Tcp, None, responses, None)
.await
.expect("names a service");
assert_eq!(verdict.service.as_deref(), Some("http"));
assert_eq!(verdict.product.as_deref(), Some("gunicorn"));
assert_eq!(verdict.version.as_deref(), Some("21.2.0"));
}
#[tokio::test]
async fn analyze_composes_curated_product_vendor_with_powered_by_extrainfo() {
let responses = ResponseSet::from_banners(vec![
"HTTP/1.1 200 OK\r\nServer: Apache/2.4.58\r\nX-Powered-By: PHP/8.2.1\r\n\r\n"
.to_string(),
]);
let service = analyze(80, Protocol::Tcp, None, responses, None)
.await
.expect("names a service")
.to_service()
.expect("projects onto a service");
assert_eq!(service.name(), "http");
assert_eq!(service.product(), Some("Apache HTTP Server"));
assert_eq!(service.vendor(), Some("Apache Software Foundation"));
assert_eq!(service.version(), Some("2.4.58"));
assert_eq!(service.extrainfo(), Some("PHP/8.2.1"));
}
#[tokio::test]
async fn analyze_resolves_a_versionless_server_to_its_name_not_generic_http() {
let responses = ResponseSet::from_banners(vec![
"HTTP/1.1 403 Forbidden\r\nServer: cloudflare\r\n\r\n".to_string(),
]);
let verdict = analyze(8000, Protocol::Tcp, None, responses, None)
.await
.expect("names a service");
assert_eq!(verdict.service.as_deref(), Some("http"));
assert_eq!(verdict.product.as_deref(), Some("cloudflare"));
}
#[tokio::test]
async fn analyze_returns_none_when_no_evidence() {
assert!(
analyze(1, Protocol::Tcp, None, ResponseSet::default(), None)
.await
.is_none()
);
}
}