nyx/src/surface/mod.rs

//! Phase 21 — attack-surface map.
//!
//! The `SurfaceMap` graph names the externally-reachable shape of the
//! project under analysis: HTTP route entry-points (Flask, FastAPI,
//! Spring, Express, …), the data stores they read/write, the external
//! services they talk to, and the local sinks they ultimately reach.
//!
//! Track G's chain composer walks this graph to translate findings into
//! cross-feature attack chains, and the `nyx surface` CLI prints a
//! human-readable tree from it.  Phase 21 ships the graph types plus
//! the first framework probe (Python + Flask); Phase 22 generalises the
//! probe to the remaining languages and Phase 23 wires the CLI.
//!
//! Storage shape: a flat `Vec<SurfaceNode>` sorted by [`SourceLocation`]
//! and a flat `Vec<SurfaceEdge>` sorted by `(from_idx, to_idx, kind)`.
//! Both vectors are byte-deterministic, so two scans of the same source
//! produce byte-identical JSON when round-tripped through SQLite.  See
//! [`graph::petgraph_view`] for a petgraph-backed view used by the
//! chain composer.

use crate::entry_points::HttpMethod;
use serde::{Deserialize, Serialize};
use std::collections::BTreeMap;
use std::path::Path;

pub mod build;
pub mod graph;
pub mod lang;

/// Stable source location used as the primary key for every
/// [`SurfaceNode`].  `file` is a project-relative POSIX path so the
/// SurfaceMap is portable across machines; `line` and `col` are
/// 1-indexed.  Ordering is `(file, line, col)` lexicographic, matching
/// the determinism the rest of the analyser uses for spans.
#[derive(Debug, Clone, PartialEq, Eq, Hash, PartialOrd, Ord, Serialize, Deserialize)]
pub struct SourceLocation {
    pub file: String,
    pub line: u32,
    pub col: u32,
}

impl SourceLocation {
    pub fn new(file: impl Into<String>, line: u32, col: u32) -> Self {
        Self {
            file: file.into(),
            line,
            col,
        }
    }
}

/// Web-framework tag attached to every [`EntryPoint`].  The set is
/// fixed in Phase 21 + 22 and matches the set of framework probes
/// behind [`lang`].  New frameworks land as new variants.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum Framework {
    Flask,
    FastApi,
    Django,
    Express,
    Spring,
    JaxRs,
    Rails,
    Sinatra,
    Axum,
    Actix,
    Rocket,
    NetHttp,
    Gin,
    NextAppRouter,
    NextServerAction,
}

/// HTTP-handler entry-point recognised by a framework probe.
///
/// Every node carries the route's declared path string, HTTP method,
/// and a resolved handler [`SourceLocation`] pointing at the function
/// definition.  `auth_required` is `true` when the decorator stack
/// (or framework equivalent) contains an auth guard the probe was
/// able to identify; Phase 21 recognises Flask's `@login_required`,
/// `@auth_required`, and `@jwt_required` decorators.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct EntryPoint {
    pub location: SourceLocation,
    pub framework: Framework,
    pub method: HttpMethod,
    pub route: String,
    pub handler_name: String,
    pub handler_location: SourceLocation,
    pub auth_required: bool,
}

/// Persistent data store reachable from the surface — SQL database,
/// key-value store, document DB, blob store.  Phase 22 populates this
/// from label-rule data-source matches and ORM-receiver type facts;
/// Phase 21 ships the type for forward-compat only and emits no
/// `DataStore` nodes.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct DataStore {
    pub location: SourceLocation,
    pub kind: DataStoreKind,
    pub label: String,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum DataStoreKind {
    Sql,
    KeyValue,
    Document,
    BlobStore,
    Filesystem,
    Unknown,
}

/// External service the surface talks to over a network — third-party
/// HTTP API, message broker, search index.  Phase 22 fills this in;
/// Phase 21 ships the type.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct ExternalService {
    pub location: SourceLocation,
    pub kind: ExternalServiceKind,
    pub label: String,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum ExternalServiceKind {
    HttpApi,
    MessageBroker,
    SearchIndex,
    AuthProvider,
    Unknown,
}

/// Local sink with no externally observable side-effect — `eval`,
/// `pickle.loads`, `subprocess.Popen`, raw SQL execute, etc.  Phase 22
/// fills this in from the existing label-rule registry; Phase 21
/// ships the type.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct DangerousLocal {
    pub location: SourceLocation,
    pub function_name: String,
    pub cap_bits: u32,
}

/// A node in the [`SurfaceMap`].  Every variant carries a
/// [`SourceLocation`] so the surface ordering is total and stable.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(tag = "node", rename_all = "snake_case")]
pub enum SurfaceNode {
    EntryPoint(EntryPoint),
    DataStore(DataStore),
    ExternalService(ExternalService),
    DangerousLocal(DangerousLocal),
}

impl SurfaceNode {
    pub fn location(&self) -> &SourceLocation {
        match self {
            SurfaceNode::EntryPoint(n) => &n.location,
            SurfaceNode::DataStore(n) => &n.location,
            SurfaceNode::ExternalService(n) => &n.location,
            SurfaceNode::DangerousLocal(n) => &n.location,
        }
    }

    /// Discriminator used as a secondary sort key so two nodes that
    /// happen to share a [`SourceLocation`] (e.g. multiple route
    /// decorators on one function) keep a deterministic relative
    /// order.  Returns the variant index in the enum declaration.
    fn kind_ordinal(&self) -> u8 {
        match self {
            SurfaceNode::EntryPoint(_) => 0,
            SurfaceNode::DataStore(_) => 1,
            SurfaceNode::ExternalService(_) => 2,
            SurfaceNode::DangerousLocal(_) => 3,
        }
    }

    /// Tertiary sort key used to disambiguate nodes that share both
    /// [`SourceLocation`] and kind — e.g. a single Flask function with
    /// two `@app.route(...)` decorators ending up at the same handler
    /// location.
    fn dedup_tag(&self) -> String {
        match self {
            SurfaceNode::EntryPoint(n) => format!("{:?}:{:?}:{}", n.framework, n.method, n.route),
            SurfaceNode::DataStore(n) => format!("{:?}:{}", n.kind, n.label),
            SurfaceNode::ExternalService(n) => format!("{:?}:{}", n.kind, n.label),
            SurfaceNode::DangerousLocal(n) => format!("{}:{:#x}", n.function_name, n.cap_bits),
        }
    }
}

/// Semantic kind of an edge in the [`SurfaceMap`].  Encodes the
/// seven edge classes the chain composer walks; persistence is via
/// JSON so adding a variant is a non-breaking schema change as long
/// as the SQLite-level migration drops the old surface_map rows.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Ord, PartialOrd, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum EdgeKind {
    /// Caller → callee.  Wraps the call-graph edge so consumers do
    /// not have to consult [`crate::callgraph::CallGraph`] directly.
    Calls,
    /// Function or entry-point reads from a data store / external
    /// service.
    ReadsFrom,
    /// Function or entry-point writes to a data store.
    WritesTo,
    /// Function or entry-point sends a request to an external
    /// service.
    TalksTo,
    /// Entry-point reaches a dangerous-local sink through some
    /// transitive call chain.
    Reaches,
    /// Entry-point triggers a side-effecting action (job, email,
    /// webhook) other than a direct call.
    Triggers,
    /// Entry-point gates downstream access on a successful auth
    /// check.  The `from` is the auth-check node, the `to` is the
    /// entry-point.
    AuthRequiredOn,
}

/// A single edge in the [`SurfaceMap`].  `from` and `to` are indices
/// into [`SurfaceMap::nodes`]; the surface ordering keeps these
/// stable across rescans.
#[derive(Debug, Clone, PartialEq, Eq, Hash, Ord, PartialOrd, Serialize, Deserialize)]
pub struct SurfaceEdge {
    pub from: u32,
    pub to: u32,
    pub kind: EdgeKind,
}

/// The attack-surface graph for a project.  Stored as parallel
/// `Vec`s keyed on [`SourceLocation`] so JSON serialisation is
/// byte-deterministic and SQLite round-trips are stable.
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
pub struct SurfaceMap {
    pub nodes: Vec<SurfaceNode>,
    pub edges: Vec<SurfaceEdge>,
}

impl SurfaceMap {
    /// Construct an empty map.
    pub fn new() -> Self {
        Self::default()
    }

    /// Total node count.  Cheap.
    pub fn node_count(&self) -> usize {
        self.nodes.len()
    }

    /// Total edge count.  Cheap.
    pub fn edge_count(&self) -> usize {
        self.edges.len()
    }

    /// Return the first entry-point node matching `(method, route)`.
    /// Linear scan; the SurfaceMap is small (one node per route +
    /// store + service + sink) so this is fine in practice.
    pub fn entry_for_route(&self, method: HttpMethod, route: &str) -> Option<&EntryPoint> {
        self.nodes.iter().find_map(|n| match n {
            SurfaceNode::EntryPoint(ep) if ep.method == method && ep.route == route => Some(ep),
            _ => None,
        })
    }

    /// Iterate over every entry-point node in surface order.
    pub fn entry_points(&self) -> impl Iterator<Item = &EntryPoint> {
        self.nodes.iter().filter_map(|n| match n {
            SurfaceNode::EntryPoint(ep) => Some(ep),
            _ => None,
        })
    }

    /// Sort nodes by `(SourceLocation, kind_ordinal, dedup_tag)` and
    /// rewrite every edge's `from`/`to` accordingly.  Two structurally
    /// identical maps are byte-identical after [`canonicalize`] +
    /// `serde_json::to_vec` regardless of insertion order.
    ///
    /// [`canonicalize`]: SurfaceMap::canonicalize
    pub fn canonicalize(&mut self) {
        if self.nodes.is_empty() {
            self.edges.sort();
            self.edges.dedup();
            return;
        }
        let mut indexed: Vec<(usize, &SurfaceNode)> = self.nodes.iter().enumerate().collect();
        indexed.sort_by(|(_, a), (_, b)| {
            let key_a = (a.location(), a.kind_ordinal(), a.dedup_tag());
            let key_b = (b.location(), b.kind_ordinal(), b.dedup_tag());
            key_a.cmp(&key_b)
        });
        let mut remap: BTreeMap<u32, u32> = BTreeMap::new();
        let mut new_nodes: Vec<SurfaceNode> = Vec::with_capacity(self.nodes.len());
        for (new_idx, (old_idx, _)) in indexed.iter().enumerate() {
            remap.insert(*old_idx as u32, new_idx as u32);
        }
        for (_, node) in indexed {
            new_nodes.push(node.clone());
        }
        for edge in &mut self.edges {
            if let Some(&new_from) = remap.get(&edge.from) {
                edge.from = new_from;
            }
            if let Some(&new_to) = remap.get(&edge.to) {
                edge.to = new_to;
            }
        }
        self.nodes = new_nodes;
        self.edges.sort();
        self.edges.dedup();
    }

    /// Serialize to deterministic JSON.  The map is canonicalised
    /// first; structurally identical maps emit byte-identical JSON.
    pub fn to_json(&mut self) -> serde_json::Result<Vec<u8>> {
        self.canonicalize();
        serde_json::to_vec(self)
    }

    /// Deserialize from JSON.  Does not canonicalise; the producer is
    /// responsible for emitting a canonicalised payload.
    pub fn from_json(bytes: &[u8]) -> serde_json::Result<Self> {
        serde_json::from_slice(bytes)
    }
}

/// Convert an absolute path to a project-relative POSIX path string.
/// Returns the absolute path verbatim when the file is outside the
/// scan root or when path stripping fails.
pub fn relative_path_string(path: &Path, scan_root: Option<&Path>) -> String {
    if let Some(root) = scan_root {
        if let Ok(rel) = path.strip_prefix(root) {
            return rel.to_string_lossy().replace('\\', "/");
        }
    }
    path.to_string_lossy().replace('\\', "/")
}

#[cfg(test)]
mod tests {
    use super::*;

    fn loc(file: &str, line: u32, col: u32) -> SourceLocation {
        SourceLocation::new(file, line, col)
    }

    fn ep(file: &str, line: u32, route: &str, method: HttpMethod) -> SurfaceNode {
        SurfaceNode::EntryPoint(EntryPoint {
            location: loc(file, line, 1),
            framework: Framework::Flask,
            method,
            route: route.into(),
            handler_name: "h".into(),
            handler_location: loc(file, line + 1, 1),
            auth_required: false,
        })
    }

    #[test]
    fn canonicalize_sorts_nodes_and_remaps_edges() {
        let mut m = SurfaceMap::new();
        m.nodes.push(ep("b.py", 10, "/b", HttpMethod::GET));
        m.nodes.push(ep("a.py", 5, "/a", HttpMethod::GET));
        m.edges.push(SurfaceEdge {
            from: 0,
            to: 1,
            kind: EdgeKind::Calls,
        });
        m.canonicalize();
        assert_eq!(m.nodes[0].location().file, "a.py");
        assert_eq!(m.nodes[1].location().file, "b.py");
        // edge `from=0` was b.py (now index 1), `to=1` was a.py (now index 0)
        assert_eq!(m.edges[0].from, 1);
        assert_eq!(m.edges[0].to, 0);
    }

    #[test]
    fn json_round_trip_byte_identical() {
        let mut a = SurfaceMap::new();
        a.nodes.push(ep("a.py", 1, "/a", HttpMethod::GET));
        a.nodes.push(ep("b.py", 2, "/b", HttpMethod::POST));
        a.edges.push(SurfaceEdge {
            from: 0,
            to: 1,
            kind: EdgeKind::Calls,
        });
        let bytes_a = a.to_json().unwrap();
        let b = SurfaceMap::from_json(&bytes_a).unwrap();
        let mut b = b;
        let bytes_b = b.to_json().unwrap();
        assert_eq!(bytes_a, bytes_b);
    }
}