pub mod model;
mod analyzer;
mod db;
mod http;
mod matcher;
mod pattern;
mod prefilter;
mod response;
mod ssh;
mod tls;
mod tls_cert;
#[cfg(test)]
mod corpus;
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 ssh::SshAnalyzer;
pub use tls_cert::TlsCertAnalyzer;
use std::time::Duration;
use tokio::io::{AsyncRead, AsyncReadExt, AsyncWrite, AsyncWriteExt};
use tokio::net::TcpStream;
use tokio::time::timeout;
use crate::core::models::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 MAX_RESPONSE_BYTES: usize = 4096;
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) -> Service {
let name = lookup_service_name(port, protocol).unwrap_or_else(|| "???".to_string());
Service::new(name, 0)
}
pub fn baseline_port(port: u16, protocol: Protocol, state: PortState) -> Port {
let mut classified = Port::new(port, protocol, state);
classified.set_service(baseline_service(port, protocol));
classified
}
pub async fn fingerprint_tcp(stream: TcpStream, mut port: Port) -> Port {
let addr = stream.peer_addr().ok();
let (responses, tunnel) = gather(stream, port.number()).await;
if responses.is_empty() {
return port;
}
let fallback = first_printable(&responses.banners);
match analyze(port.number(), addr, responses, tunnel).await {
Some(verdict) if !verdict.is_empty() => {
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
}
async fn gather(mut stream: TcpStream, port: u16) -> (ResponseSet, Option<Tunnel>) {
let peer = stream.peer_addr().ok().map(|addr| addr.ip());
if tls::is_tls_port(port) {
return match peer {
Some(ip) => tunneled(tls::handshake(stream, ip).await, port).await,
None => (ResponseSet::default(), None),
};
}
let had_probes = !SignatureDb::global().tcp_probe_payloads(port).is_empty();
let banners = collect_responses(&mut stream, port).await;
if !banners.is_empty() || had_probes {
return (ResponseSet::from_banners(banners), None);
}
match peer {
Some(ip) => tunneled(tls::speculative_handshake(stream, ip).await, port).await,
None => (ResponseSet::default(), None),
}
}
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 banners = collect_responses(&mut tunnel, port).await;
let responses = ResponseSet {
banners,
tls: Some(info),
};
(responses, Some(Tunnel::Tls))
}
async fn collect_responses<S>(stream: &mut S, port: u16) -> 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 SignatureDb::global().tcp_probe_payloads(port) {
if stream.write_all(payload).await.is_err() {
break;
}
if let Some(reply) = read_response(stream, PROBE_READ_TIMEOUT).await {
banners.push(reply);
}
}
banners
}
static ANALYZERS: &[&dyn Analyzer] = &[
&BannerRegexAnalyzer,
&HttpHeadersAnalyzer,
&SshAnalyzer,
&TlsCertAnalyzer,
];
async fn analyze(
port: u16,
addr: Option<std::net::SocketAddr>,
responses: ResponseSet,
tunnel: Option<Tunnel>,
) -> Option<ServiceVerdict> {
let ctx = PortContext { port, 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,
{
let mut buffer = [0u8; MAX_RESPONSE_BYTES];
match timeout(wait, stream.read(&mut buffer)).await {
Ok(Ok(n)) if n > 0 => Some(String::from_utf8_lossy(&buffer[..n]).into_owned()),
_ => None,
}
}
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 {
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, 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, 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, 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, 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, None, ResponseSet::default(), None)
.await
.is_none()
);
}
}