javaprogram

package
v0.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 26, 2026 License: Apache-2.0 Imports: 7 Imported by: 0

Documentation

Overview

Package javaprogram defines the deterministic, source-only semantic facts used by Java value-flow taint. It is the Java twin of jsprogram/pythonprogram: the model is parser-independent, tree-sitter is confined to the synapse-ast infrastructure sidecar, and every document is validated here before a use case trusts it. The Java-level differences from JS are: symbol kinds cover classes/interfaces/methods/constructors and lambdas; imports are single-type / static / on-demand rather than named/default; symbols and PARAMETERS carry Annotations (so a Spring `@RequestParam`/`@RequestBody`/`@PathVariable` parameter can be modeled as a tainted source); modules are identified by source PATH; and symbol ids use a "java:" prefix.

Index

Constants

View Source 
const (
	// SchemaVersion is the only semantic-facts wire version this build understands.
	SchemaVersion = 1
)

Variables

This section is empty.

Functions

func CanonicalSymbolID 

func CanonicalSymbolID(module, qualified string) string

CanonicalSymbolID builds the stable id for a Java symbol: "java:" + module path + ":" + qualified name.

Types

type Argument 

type Argument struct {
	Spread  bool      `json:"spread,omitempty"`
	Value   Reference `json:"value"`
	ValueID string    `json:"value_id,omitempty"`
	Pos     Position  `json:"position,omitempty"`
}

Argument is one call argument. Java has no spread; Spread is retained for model parity and is normally false.

type Assignment 

type Assignment struct {
	ScopeID      string      `json:"scope_id"`
	Targets      []Reference `json:"targets"`
	TargetIDs    []string    `json:"target_ids,omitempty"`
	Value        Reference   `json:"value"`
	ValueID      string      `json:"value_id,omitempty"`
	StrongUpdate bool        `json:"strong_update,omitempty"`
	Pos          Position    `json:"position"`
}

Assignment captures a binding/value relationship without retaining expression text. StrongUpdate means the extractor proved a local string-literal assignment executes on every path reaching the following statement in the same callable. Consumers may replace earlier bindings only when this marker is present.

type Call 

type Call struct {
	ID              string      `json:"id"`
	CallerID        string      `json:"caller_id"`
	Callee          Reference   `json:"callee"`
	Arguments       []Argument  `json:"arguments,omitempty"`
	ResultID        string      `json:"result_id,omitempty"`
	ReceiverValueID string      `json:"receiver_value_id,omitempty"`
	Pos             Position    `json:"position"`
	Await           bool        `json:"await,omitempty"` // unused for Java; kept for model parity
	New             bool        `json:"new,omitempty"`   // a `new X(...)` constructor call
	OutputProof     OutputProof `json:"output_proof,omitempty"`
}

Call is one syntactic method invocation or `new` (object_creation_expression) owned by CallerID. Callee is a name/member reference when statically expressible, otherwise ReferenceUnknown; the extractor then also records a GapUnresolvedCall so absence is not read as proof. Validate stays lenient about this pairing: a valid source file must never have its whole facts document rejected, so a missing gap is not an error.

type CoverageGap 

type CoverageGap struct {
	Kind     GapKind  `json:"kind"`
	SymbolID string   `json:"symbol_id,omitempty"`
	Detail   string   `json:"detail,omitempty"`
	Pos      Position `json:"position"`
}

CoverageGap is an explicit reason a complete negative is unsafe. Detail is a trusted closed label.

type Document 

type Document struct {
	SchemaVersion int              `json:"schema_version"`
	Modules       []Module         `json:"modules"`
	Symbols       []Symbol         `json:"symbols"`
	Imports       []Import         `json:"imports"`
	Calls         []Call           `json:"calls"`
	Assignments   []Assignment     `json:"assignments"`
	Returns       []Return         `json:"returns"`
	Values        []Value          `json:"values"`
	Flows         []ValueFlow      `json:"flows"`
	Entrypoints   []EntrypointHint `json:"entrypoint_hints"`
	CoverageGaps  []CoverageGap    `json:"coverage_gaps"`
	FilesSeen     int              `json:"files_seen"`
	FilesParsed   int              `json:"files_parsed"`
	NodesSeen     int              `json:"nodes_seen"`
	Truncated     bool             `json:"truncated"`
}

Document is the complete versioned facts result for one source root.

func (Document) Complete 

func (d Document) Complete() bool

Complete reports whether the document can support a negative proof.

func (*Document) SortCanonical 

func (d *Document) SortCanonical()

SortCanonical makes serialization and downstream graph construction independent of map/parser order.

func (Document) Validate 

func (d Document) Validate() error

Validate rejects malformed or unbounded sidecar output at the trust boundary.

type EntrypointHint 

type EntrypointHint struct {
	SymbolID string   `json:"symbol_id"`
	Kind     string   `json:"kind"`
	Pos      Position `json:"position"`
}

EntrypointHint is a syntactic framework/application entrypoint cue (a @RestController mapping, `main`).

type GapKind 

type GapKind string

GapKind is a closed reason code explaining why absence cannot be treated as proof. 

const (
	GapParseRecovery    GapKind = "parse_recovery"
	GapDynamicImport    GapKind = "dynamic_import"
	GapDynamicExecution GapKind = "dynamic_execution" // reflection, ScriptEngine, dynamic proxy
	GapUnresolvedImport GapKind = "unresolved_import"
	GapUnresolvedCall   GapKind = "unresolved_call"
	GapUnresolvedValue  GapKind = "unresolved_value"
	GapDynamicAttribute GapKind = "dynamic_attribute"
	GapBudget           GapKind = "budget"
	GapUnreadable       GapKind = "unreadable"
)

func (GapKind) Valid 

func (k GapKind) Valid() bool

type Import 

type Import struct {
	ScopeID string     `json:"scope_id"`
	Kind    ImportKind `json:"kind"`
	Module  string     `json:"module"`
	Name    string     `json:"name,omitempty"`  // the imported simple name (empty for on-demand)
	Alias   string     `json:"alias,omitempty"` // Java has no import aliasing; kept for model parity, normally empty
	Pos     Position   `json:"position"`
}

Import records one import declaration. Module is the imported package or type ("java.sql.Statement", "java.util", "org.springframework.web.bind.annotation").

type ImportKind 

type ImportKind string

ImportKind records how a name entered the compilation unit. Together with Module (the imported package or type) it lets the taint catalog match a sink/source to its package without resolving the classpath. 

const (
	ImportSingle         ImportKind = "single"           // import java.sql.Statement;
	ImportStatic         ImportKind = "static"           // import static java.lang.Math.max;
	ImportOnDemand       ImportKind = "on_demand"        // import java.sql.*;
	ImportStaticOnDemand ImportKind = "static_on_demand" // import static java.lang.Math.*;
)

func (ImportKind) Valid 

func (k ImportKind) Valid() bool

type Module 

type Module struct {
	Name    string   `json:"name"`
	File    string   `json:"file"`
	Package string   `json:"package,omitempty"`
	Pos     Position `json:"position"`
}

Module associates a canonical module candidate (its source path without extension) with its source file. Package is the file's `package` declaration (dotted, e.g. "com.example.util"), empty for the default package. It lets the value-flow engine map a static import (`import static com.example.util.X.m`) to the in-document type by its fully-qualified name, which the file-path Name cannot express.

type OutputProof 

type OutputProof string

OutputProof is a source-only, extractor-proven output context. The empty value means no proof. It never carries source text; consumers must treat an absent proof from an older sidecar as unproved. 

const (
	OutputProofNone     OutputProof = ""
	OutputProofHTMLText OutputProof = "html_text"
)

func (OutputProof) Valid 

func (p OutputProof) Valid() bool

type Parameter 

type Parameter struct {
	Name        string        `json:"name"`
	Kind        ParameterKind `json:"kind"`
	ValueID     string        `json:"value_id,omitempty"`
	Annotations []Reference   `json:"annotations,omitempty"`
	Pos         Position      `json:"position"`
}

Parameter is one method/constructor parameter in declaration order. Annotations carries its Java annotations (e.g. @RequestParam) so an annotation-driven web input can be modeled as a source.

type ParameterKind 

type ParameterKind string

ParameterKind preserves Java parameter-binding semantics without carrying type/annotation text. 

const (
	ParameterPositional ParameterKind = "positional"
	ParameterVararg     ParameterKind = "vararg" // String... args
)

func (ParameterKind) Valid 

func (k ParameterKind) Valid() bool

type Position 

type Position struct {
	File   string `json:"file"`
	Line   int    `json:"line"`
	Column int    `json:"column"`
}

Position is a normalized, relative source location. Column is zero-based, Line is one-based.

type Reference 

type Reference struct {
	Kind     ReferenceKind `json:"kind"`
	Segments []string      `json:"segments,omitempty"`
}

Reference is a safe expression summary such as ["request", "getParameter"]. No source body or literal value is retained. Literal references only carry Kind, not their value.

type ReferenceKind 

type ReferenceKind string

ReferenceKind describes a bounded expression shape. It intentionally excludes arbitrary source text. 

const (
	ReferenceName       ReferenceKind = "name"
	ReferenceAttribute  ReferenceKind = "attribute" // field access a.b.c
	ReferenceCall       ReferenceKind = "call"
	ReferenceExpression ReferenceKind = "expression"
	ReferenceLiteral    ReferenceKind = "literal"
	ReferenceUnknown    ReferenceKind = "unknown"
)

func (ReferenceKind) Valid 

func (k ReferenceKind) Valid() bool

type Return 

type Return struct {
	ScopeID string    `json:"scope_id"`
	Value   Reference `json:"value"`
	ValueID string    `json:"value_id,omitempty"`
	SlotID  string    `json:"slot_id,omitempty"`
	Pos     Position  `json:"position"`
}

Return captures a method return expression summary.

type Symbol 

type Symbol struct {
	ID            string      `json:"id"`
	Module        string      `json:"module"`
	QualifiedName string      `json:"qualified_name"`
	Name          string      `json:"name"`
	ParentID      string      `json:"parent_id,omitempty"`
	Kind          SymbolKind  `json:"kind"`
	Pos           Position    `json:"position"`
	Parameters    []Parameter `json:"parameters,omitempty"`
	Annotations   []Reference `json:"annotations,omitempty"` // @RestController, @RequestMapping, ...
	Bases         []Reference `json:"bases,omitempty"`       // extends/implements references
}

Symbol is a module, class, interface, method, constructor, or lambda declaration.

type SymbolKind 

type SymbolKind string

SymbolKind identifies a Java declaration that owns a lexical scope or can appear in a call graph. 

const (
	SymbolModule      SymbolKind = "module"
	SymbolClass       SymbolKind = "class"
	SymbolInterface   SymbolKind = "interface"
	SymbolMethod      SymbolKind = "method"
	SymbolConstructor SymbolKind = "constructor"
	SymbolLambda      SymbolKind = "lambda" // a Java lambda / anonymous-class body (the analog of a JS arrow)
)

func (SymbolKind) Valid 

func (k SymbolKind) Valid() bool

type Value 

type Value struct {
	ID      string    `json:"id"`
	ScopeID string    `json:"scope_id"`
	Kind    ValueKind `json:"kind"`
	Name    string    `json:"name,omitempty"`
	Ref     Reference `json:"reference"`
	Pos     Position  `json:"position"`
}

Value is one stable value slot. Ref carries only a bounded semantic shape; source text is never kept.

type ValueFlow 

type ValueFlow struct {
	FromID string        `json:"from_id"`
	ToID   string        `json:"to_id"`
	Kind   ValueFlowKind `json:"kind"`
	Pos    Position      `json:"position"`
}

ValueFlow says a value can propagate from one slot to another inside the same Java method.

type ValueFlowKind 

type ValueFlowKind string

ValueFlowKind is a closed intra-procedural propagation operation emitted by the sidecar. 

const (
	FlowExpression ValueFlowKind = "expression"
	FlowAttribute  ValueFlowKind = "attribute"
	FlowAssignment ValueFlowKind = "assignment"
	FlowReturn     ValueFlowKind = "return"
)

func (ValueFlowKind) Valid 

func (k ValueFlowKind) Valid() bool

type ValueKind 

type ValueKind string

ValueKind identifies a source-level value slot used by the interprocedural taint engine. 

const (
	ValueParameter  ValueKind = "parameter"
	ValueBinding    ValueKind = "binding"
	ValueReference  ValueKind = "reference"
	ValueCallResult ValueKind = "call_result"
	ValueExpression ValueKind = "expression"
	ValueLiteral    ValueKind = "literal"
	ValueReturn     ValueKind = "return"
)

func (ValueKind) Valid 

func (k ValueKind) Valid() bool

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.