traversal

Documentation

Overview

Package traversal provides a reusable graph traversal engine for the DevOps-Proxy asset graph. It is purely algorithmic — it contains no business logic, no rule matching, and no scoring. Higher-level packages (internal/engine, internal/graph/blast) call it to discover paths and reachable nodes without implementing their own BFS/DFS loops.

Circular-dependency note: this package imports internal/graph. The parent package (internal/graph) does NOT import traversal; blast.go keeps its own BFS so the two can coexist without a cycle.

Index

• func FindSensitiveResources(g *graph.Graph, startNodeID string) []*graph.Node
• func GetNeighbors(g *graph.Graph, nodeID string) []string
• func NodeType(g *graph.Graph, nodeID string) string
• type TraversalOptions
• type TraversalResult
  • func TraverseFromNode(g *graph.Graph, startNodeID string, opts TraversalOptions) []TraversalResult

Functions

func FindSensitiveResources

func FindSensitiveResources(g *graph.Graph, startNodeID string) []*graph.Node

FindSensitiveResources enumerates all cloud resource nodes reachable from startNodeID via identity/access edges (RUNS_AS, RUNS_ON, ASSUMES_ROLE, CAN_ACCESS) whose sensitivity metadata is "high".

This is the traversal-engine equivalent of the BFS performed by internal/graph.ComputeBlastRadius; both produce the same set of HIGH sensitive resources. Results are sorted by Name ascending.

func GetNeighbors

func GetNeighbors(g *graph.Graph, nodeID string) []string

GetNeighbors returns the IDs of all nodes directly reachable from nodeID via any outgoing edge. The order follows the graph's edge insertion order.

func NodeType

func NodeType(g *graph.Graph, nodeID string) string

NodeType returns the string representation of the NodeType for nodeID, or an empty string when the node does not exist.

Types

type TraversalOptions

type TraversalOptions struct {
	// AllowedEdgeTypes restricts which edge types are followed.
	// When empty (nil or zero-length) ALL edge types are followed.
	AllowedEdgeTypes []graph.EdgeType
}

TraversalOptions configures a TraverseFromNode call.

type TraversalResult

type TraversalResult struct {
	// Nodes contains the ordered node IDs from start to leaf (inclusive).
	Nodes []string

	// Edges contains human-readable edge descriptors in the form "fromID→toID",
	// one entry per hop.  len(Edges) == len(Nodes)-1.
	Edges []string
}

TraversalResult represents a single complete path discovered during traversal, from the start node to a leaf node (a node with no further allowed outgoing edges, or all outgoing neighbours already on this path).

func TraverseFromNode

func TraverseFromNode(g *graph.Graph, startNodeID string, opts TraversalOptions) []TraversalResult

TraverseFromNode performs a depth-first enumeration of all distinct paths reachable from startNodeID in g.

Behaviour:

• Only edges whose type is in opts.AllowedEdgeTypes are followed; when AllowedEdgeTypes is empty every edge type is eligible.
• A node may not appear twice within the same path (cycle protection).
• Paths of length zero (start node with no eligible neighbours) are not returned.
• The function returns nil when startNodeID does not exist in g.