Documentation
¶
Overview ¶
Package resolver — FROZEN CONTRACT DRAFT (v1alpha1).
This file defines the interface and output types of the effective posture resolver. Move it to internal/resolver/ during M0 scaffolding; from then on, changes to exported types in this file require human approval.
Resolver versions are a stable, comma-separated list of subsystem tags in the order mTLS, authorization (for example, mtls/v5,authz/v8). Bump only the tag whose precedence, interpretation, or unknown-propagation semantics change, and add or update table coverage for that behavior.
INVARIANTS (enforced by tests and lint):
- This package is PURE: no client-go imports, no I/O, no globals, no clock. Inputs arrive fully normalized; outputs are deterministic.
- Every non-unknown conclusion carries a non-empty resolution Chain.
- Unknown is an explicit value, never a zero-value fallthrough.
Index ¶
- type AuthorizationPolicyView
- type AuthzEffective
- type AuthzResult
- type DataPlaneMode
- type DestinationRuleView
- type MTLSEffective
- type MTLSResult
- type MeshDefaults
- type NamespaceInput
- type PeerAuthenticationView
- type Resolver
- type ResolverV2
- type Step
- type Tristate
- type WaypointView
- type WorkloadInput
- type WorkloadRef
- type WorkloadResult
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type AuthorizationPolicyView ¶
type AuthorizationPolicyView struct {
Name, Namespace string
Action string // ALLOW | DENY | CUSTOM | AUDIT
HasSelector bool
SelectorMatch bool
TargetsWaypoint bool // attached via targetRefs to a waypoint/Gateway
TargetRefKind string
TargetRefName string
TargetWaypoint *WaypointView // waypoint selected for this exact targetRef attachment
RequiresL7 bool // rule uses L7-only attributes (methods, paths, headers, request principals, ...)
HasRules bool // distinguishes spec: {} from rules: [{}]
BroadAllow bool // unrestricted rule or wildcard source hint; ignored when HasRules is false
IdentityScoped bool // every matching ALLOW rule is constrained to explicit workload identity
RootNamespace bool // lives in the mesh root namespace
}
type AuthzEffective ¶
type AuthzEffective string
const ( AuthzDefaultDenyExplicitAllow AuthzEffective = "default-deny-explicit-allow" AuthzAllowOnly AuthzEffective = "allow-only" AuthzNoPolicy AuthzEffective = "no-policy" AuthzDenyPresent AuthzEffective = "deny-present" AuthzWaypointUnenforced AuthzEffective = "waypoint-policy-unenforced" AuthzNotInMesh AuthzEffective = "not-in-mesh" AuthzUnknown AuthzEffective = "unknown" )
type AuthzResult ¶
type AuthzResult struct {
Effective AuthzEffective `json:"effective"`
BroadAllow *bool `json:"broadAllow,omitempty"`
IdentityScoped *bool `json:"identityScoped,omitempty"`
PoliciesInScope []string `json:"policiesInScope,omitempty"` // "namespace/name"
WaypointUnenforced []string `json:"waypointUnenforced,omitempty"`
Chain []Step `json:"chain"`
UnknownReason string `json:"unknownReason,omitempty"`
}
type DataPlaneMode ¶
type DataPlaneMode string
const ( ModeSidecar DataPlaneMode = "sidecar" ModeAmbient DataPlaneMode = "ambient" ModeMixed DataPlaneMode = "mixed" ModeUnknown DataPlaneMode = "unknown" ModeNotApplicable DataPlaneMode = "not-applicable" )
type DestinationRuleView ¶
type MTLSEffective ¶
type MTLSEffective string
const ( MTLSStrict MTLSEffective = "strict" MTLSPermissive MTLSEffective = "permissive" MTLSDisabled MTLSEffective = "disabled" MTLSMixedByPort MTLSEffective = "mixed-by-port" MTLSNotInMesh MTLSEffective = "not-in-mesh" MTLSUnknown MTLSEffective = "unknown" )
type MTLSResult ¶
type MTLSResult struct {
Effective MTLSEffective `json:"effective"`
ByPort map[int32]MTLSEffective `json:"byPort,omitempty"`
ClientTLSContradiction *bool `json:"clientTLSContradiction,omitempty"`
Chain []Step `json:"chain"`
UnknownReason string `json:"unknownReason,omitempty"` // required when Effective == unknown
}
type MeshDefaults ¶
type NamespaceInput ¶
type PeerAuthenticationView ¶
type PeerAuthenticationView struct {
Name, Namespace string
SelectorMatch bool // whether it selected this workload specifically
CreationTimestamp time.Time // Kubernetes metadata.creationTimestamp for oldest-policy tie-breaks
Mode string // UNSET | DISABLE | PERMISSIVE | STRICT
PortLevelModes map[int32]string
}
PeerAuthenticationView, DestinationRuleView, AuthorizationPolicyView, and WaypointView are normalized projections of the corresponding Istio resources containing only the fields the resolver consumes. Defined in M2/M5 alongside the normalizer; they must remain client-go-free (plain structs).
type Resolver ¶
type Resolver interface {
Version() string
ResolveMTLS(in WorkloadInput) MTLSResult
ResolveAuthz(in WorkloadInput) AuthzResult
}
Resolver computes effective posture. Implementations must be deterministic and side-effect free. Version() identifies the semantics version recorded in report output as scanner.resolverVersion; it changes whenever precedence or interpretation logic changes, with a corresponding entry in the test tables.
type ResolverV2 ¶
type ResolverV2 struct{}
ResolverV2 implements the current composite resolver semantics.
func (ResolverV2) ResolveAuthz ¶
func (ResolverV2) ResolveAuthz(in WorkloadInput) AuthzResult
ResolveAuthz implements Istio's additive CUSTOM -> DENY -> ALLOW evaluation model. Scope filtering remains explicit in the chain so a selector mismatch is distinguishable from the complete absence of authorization policy.
Istio policy evaluation and additive merge semantics: https://istio.io/latest/docs/concepts/security/#implicit-enablement Empty ALLOW policy and rules: [{}] distinction: https://istio.io/latest/docs/reference/config/security/authorization-policy/
func (ResolverV2) ResolveMTLS ¶
func (ResolverV2) ResolveMTLS(in WorkloadInput) MTLSResult
func (ResolverV2) Version ¶
func (ResolverV2) Version() string
type Step ¶
type Step struct {
Order int `json:"order"`
Kind string `json:"kind"` // PeerAuthentication, DestinationRule, AuthorizationPolicy, MeshConfigDefault, ...
Name string `json:"name,omitempty"`
Namespace string `json:"namespace,omitempty"`
Field string `json:"field,omitempty"` // e.g. spec.mtls.mode, spec.portLevelMtls["8080"]
Effect string `json:"effect"` // human-readable contribution of this step
}
Step is one entry in the ordered chain of resources and rules that produced a resolved conclusion. Order starts at 1 (lowest-precedence input) and ends at the step that finalized the result.
type WaypointView ¶
type WorkloadInput ¶
type WorkloadInput struct {
Ref WorkloadRef
Labels map[string]string
Ports []int32 // nil when unavailable; non-nil empty when observed with no declared ports
DataPlaneMode DataPlaneMode
Namespace NamespaceInput
MeshDefaults MeshDefaults
PeerAuthN []PeerAuthenticationView // all PAs whose scope includes this workload
DestRules []DestinationRuleView // DRs whose host selection targets this workload's services
// DestinationRulesKnown distinguishes a completed collection with no
// matching DestinationRules from unavailable DestinationRule evidence.
DestinationRulesKnown bool
AuthzPolicies []AuthorizationPolicyView // nil when collection was unavailable
// Waypoint is nil when waypoint evidence was collected and no waypoint
// serves the workload. A non-nil view with Known=false records unavailable
// Gateway API evidence without inventing a missing waypoint conclusion.
Waypoint *WaypointView
ZtunnelOnNode Tristate // ambient: ztunnel health on the workload's node(s)
}
WorkloadInput is the normalized view of one workload plus every policy resource that could influence its posture. The normalizer is responsible for scoping (Sidecar resources, exportTo, revision/namespace selection); the resolver is responsible for precedence and semantics.
type WorkloadRef ¶
type WorkloadResult ¶
type WorkloadResult struct {
Ref WorkloadRef `json:"workload"`
Mode DataPlaneMode `json:"dataPlaneMode"`
MTLS MTLSResult `json:"mtls"`
Authz AuthzResult `json:"authorization"`
}