The highest tagged major version is
Documentation
¶
Overview ¶
Package api is the public, library-shaped surface of Semantic Firewall. The CLI in cmd/sfw and the MCP server in the sibling semantic_firewall_mcp repo both consume it; everything in internal/cli is implementation glue that orchestrates flag parsing and process boundaries on top of the entry points defined here.
The entry points return the same JSON-serialisable types from pkg/models that the CLI prints, so callers can either marshal them directly or inspect the structured values in-process.
Index ¶
- func CalculateTopologyDelta(oldT, newT *topology.FunctionTopology) (string, int)
- func CompareFunctions(funcName string, oldResult, newResult diff.FingerprintResult) models.FunctionDiff
- func Diff(oldPath, newPath string) (*models.DiffOutput, error)
- func DiffWithFS(fsys FileSystem, oldPath, newPath string) (*models.DiffOutput, error)
- func ShortFunctionName(fullName string) string
- type FileSystem
- type RealFileSystem
- func (RealFileSystem) Abs(path string) (string, error)
- func (RealFileSystem) Getwd() (string, error)
- func (RealFileSystem) Open(name string) (fs.File, error)
- func (RealFileSystem) ReadFile(name string) ([]byte, error)
- func (RealFileSystem) Stat(name string) (os.FileInfo, error)
- func (RealFileSystem) WalkDir(root string, fn fs.WalkDirFunc) error
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CalculateTopologyDelta ¶
func CalculateTopologyDelta(oldT, newT *topology.FunctionTopology) (string, int)
CalculateTopologyDelta diffs two function topologies and returns a short human label plus a heuristic risk score. A nil oldT means the function is new. Newly reached capabilities (process execution, raw syscalls, plugins, network, reflective invocation, filesystem mutation), new goroutines and obfuscation each reach models.RiskScoreHigh on their own; ordinary call, loop and branch churn is capped below it. Removing structure is neutral.
func CompareFunctions ¶
func CompareFunctions(funcName string, oldResult, newResult diff.FingerprintResult) models.FunctionDiff
CompareFunctions reduces two FingerprintResult values to a FunctionDiff. A function is preserved only when its canonical IR is unchanged with every literal kept: the default fingerprint masks strings and larger integers, so on its own it would report a changed URL, command, size limit or permission mode as preserved. Otherwise the Zipper computes the structural delta, falling back to "modified" if SSA reconstruction fails.
func Diff ¶
func Diff(oldPath, newPath string) (*models.DiffOutput, error)
Diff is the convenience entry point: it computes a semantic diff between two on-disk Go source files using the real filesystem. Either path may be empty or non-existent to represent an added or removed file.
func DiffWithFS ¶
func DiffWithFS(fsys FileSystem, oldPath, newPath string) (*models.DiffOutput, error)
DiffWithFS performs a semantic diff against the supplied FileSystem so tests can drive the pipeline without touching disk. Behaviour is identical to Diff otherwise.
func ShortFunctionName ¶
ShortFunctionName strips package paths and qualifying identifiers from a Go SSA function name so it is readable in diffs and reports.
It handles three shapes:
- "fmt.Println" -> "Println"
- "pkg.(*Type).Method" / "(*pkg.Type).Method" -> "(*Type).Method"
- Generics like "pkg.Func[a/b.T]" -> "Func[a/b.T]"
Brackets and parens are tracked so qualified types inside generic parameters or receiver positions are preserved verbatim.
Types ¶
type FileSystem ¶
type FileSystem interface {
Stat(name string) (os.FileInfo, error)
Open(name string) (fs.File, error)
Getwd() (string, error)
Abs(path string) (string, error)
WalkDir(root string, fn fs.WalkDirFunc) error
ReadFile(name string) ([]byte, error)
}
FileSystem abstracts the OS file operations the analysis pipeline needs. Production code uses RealFileSystem; tests can substitute a mock to drive the pipeline without touching disk.
type RealFileSystem ¶
type RealFileSystem struct{}
RealFileSystem is the production FileSystem implementation backed by the os and filepath packages. ReadFile bounds the read at models.MaxSourceFileSize so a hostile/oversize input cannot exhaust memory.
func (RealFileSystem) Getwd ¶
func (RealFileSystem) Getwd() (string, error)
func (RealFileSystem) WalkDir ¶
func (RealFileSystem) WalkDir(root string, fn fs.WalkDirFunc) error
Source Files