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 ResultName(r diff.FingerprintResult) string
- func SSAFunctionName(fn *ssa.Function) string
- 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. Any other function is modified; the Zipper only supplies the instruction-level evidence. Its alignment is driven by data flow, so it must not decide the status: a swapped branch or a call moved out of its guard aligns completely.
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 ResultName ¶ added in v5.2.0
func ResultName(r diff.FingerprintResult) string
ResultName is the name reported for a fingerprinted function: its SSAFunctionName, or ShortFunctionName of its full name when the result carries no SSA function.
func SSAFunctionName ¶ added in v5.2.0
SSAFunctionName returns fn's name relative to its own package: "F", "(*T).M", "F$1". Unlike ShortFunctionName it does not have to guess where the package path ends, so a package whose last path element contains a dot ("gopkg.in/yaml.v3", "example.com/lib.v2") is stripped completely.
func ShortFunctionName ¶
ShortFunctionName strips package paths and qualifying identifiers from a Go SSA function name so it is readable in diffs and reports. Given only the string, it takes the text up to the first dot after the last slash as the package name; prefer SSAFunctionName when the function is at hand.
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