Struct paralegal_policy::context::Context

pub struct Context {
    marker_to_ids: HashMap<Marker, MarkerTargets>,
    desc: ProgramDescription,
    flows_to: Option<HashMap<Endpoint, CtrlFlowsTo>>,
    pub(crate) diagnostics: DiagnosticsRecorder,
    name_map: HashMap<Identifier, Vec<DefId>>,
    pub(crate) config: Arc<Config>,
    pub(crate) stats: ContextStats,
}

Interface for defining policies.

Holds a PDG (Self::desc) and defines basic queries like Self::all_nodes_for_ctrl and combinators such as Self::always_happens_before. These should be composed into more complex policies.

To communicate the results of your policies with the user you can emit diagnostic messages. To communicate a policy failure use error or the crate::assert_error macro. To communicate suspicious circumstances that are not outright cause for failure use warning or assert_warning. For all types of errors, including those with span information for a particular node, see the crate::Diagnostics trait.

Note that these methods just queue the diagnostics messages. To emit them (and potentially terminate the program if the policy does not hold) use Self::emit_diagnostics. If you used super::GraphLocation::with_context this will be done automatically for you.

Fields

marker_to_ids: HashMap<Marker, MarkerTargets>

desc: ProgramDescription

flows_to: Option<HashMap<Endpoint, CtrlFlowsTo>>

diagnostics: DiagnosticsRecorder

name_map: HashMap<Identifier, Vec<DefId>>

config: Arc<Config>

stats: ContextStats

Implementations

impl Context

pub fn always_happens_before( &self, starting_points: impl IntoIterator<Item = GlobalNode>, is_checkpoint: impl FnMut(GlobalNode) -> bool, is_terminal: impl FnMut(GlobalNode) -> bool ) -> Result<AlwaysHappensBefore>

Enforce that on every data flow path from the starting_points to is_terminal a node satisfying is_checkpoint is passed.

Fails if ctrl_id on a provided starting point is not found.

The return value contains some statistics information about the traversal. The property holds if AlwaysHappensBefore::holds is true.

Note that is_checkpoint and is_terminal will be called many times and should thus be efficient computations. In addition they should always return the same result for the same input.

impl Context

pub fn new(desc: ProgramDescription, config: Config) -> Self

Construct a Context from a ProgramDescription.

This also precomputes some data structures like an index over markers.

pub fn associated_call_site(&self, node: GlobalNode) -> CallString

👎Deprecated: Use NodeExt::associated_call_site instead

Find the call string for the statement or function that produced this node.

pub fn consuming_call_sites( &self, node: GlobalNode ) -> impl Iterator<Item = CallString> + '_

👎Deprecated: Use NodeQueries::consuming_call_sites instead

Call sites that consume this node directly. E.g. the outgoing edges.

pub fn controllers_by_name( &self, name: Identifier ) -> impl Iterator<Item = Endpoint> + '_

Find all controllers that bare this name.

This function is intended for use in writing test cases. Actual policies should generally refrain from working with controller names, other than printing them in error messages or for debugging. Policies contingent on controller names are likely unsound.

pub fn controller_by_name(&self, name: Identifier) -> Result<Endpoint>

Find a singular controller with this name.

This function should only be used in tests as the same caveats apply as in Self::controllers_by_name.

Returns Err

If there is not exactly one controller of this name.

pub fn find_by_name(&self, name: impl AsRef<str>) -> Result<DefId>

Find a type, controller or function id by its name.

Since many often share the same name this can fail with too many candidates. To handle such cases use Self::find_by_path or Self::find_all_by_name.

pub fn find_all_by_name(&self, name: impl AsRef<str>) -> Result<&[DefId]>

Find all types, controllers and functions with this name.

pub fn find_by_path(&self, path: impl AsRef<[Identifier]>) -> Result<DefId>

Find a type, controller or function with this path.

pub fn emit_diagnostics_may_exit(&self, w: impl Write) -> Result<()>

Dispatch and drain all queued diagnostics, aborts the program if any of them demand failure.

pub fn emit_diagnostics(&self, w: impl Write) -> Result<bool>

Dispatch and drain all queued diagnostics without aborting the program.

pub fn all_nodes(&self) -> impl Iterator<Item = GlobalNode> + '_

Returns all nodes that are in any of the PDGs

pub fn roots_where<'a>( &'a self, f: impl Fn(GlobalNode) -> bool + 'a ) -> impl Iterator<Item = GlobalNode> + 'a

Return nodes that satisfy the predicate and which have no ancestors that satisfy the same predicate.

pub fn report_marker_if_absent(&self, marker: Marker)

Emit a warning if this marker was not found in the source code.

fn build_index_on_markers( desc: &ProgramDescription ) -> HashMap<Marker, MarkerTargets>

fn build_flows_to(desc: &ProgramDescription) -> HashMap<Endpoint, CtrlFlowsTo>

pub fn flows_to( &self, src: impl IntoIterGlobalNodes, sink: impl IntoIterGlobalNodes, edge_type: EdgeSelection ) -> bool

👎Deprecated: Use NodeQueries::flows_to instead

Returns whether a node flows to a node through the configured edge type.

Nodes do not flow to themselves. CallArgument nodes do flow to their respective CallSites.

If you use flows_to with EdgeSelection::Control, you might want to consider using Context::has_ctrl_influence, which additionally considers intermediate nodes which the src node has data flow to and has ctrl influence on the sink.

pub fn nodes_marked_via_type( &self, marker: Marker ) -> impl Iterator<Item = GlobalNode> + '_

All nodes that have this marker through a type

pub fn nodes_marked_any_way( &self, marker: Marker ) -> impl Iterator<Item = GlobalNode> + '_

All nodes with this marker, be that via type or directly

pub fn controller_argument( &self, ctrl_id: Endpoint, index: u32 ) -> Option<GlobalNode>

Find the node that represents the indexth argument of the controller ctrl_id.

Returns None

If the controller with this id does not exist or the controller has fewer than index arguments.

pub fn has_ctrl_influence( &self, influencer: impl IntoIterGlobalNodes + Sized + Copy, target: impl IntoIterGlobalNodes + Sized + Copy ) -> bool

Returns whether there is direct control flow influence from influencer to sink, or there is some node which is data-flow influenced by influencer and has direct control flow influence on target. Or as expressed in code:

some n where self.flows_to(influencer, n, EdgeSelection::Data) && self.flows_to(n, target, EdgeSelection::Control).

pub fn influencers( &self, sink: impl IntoIterGlobalNodes + Sized, edge_type: EdgeSelection ) -> impl Iterator<Item = GlobalNode> + '_

Returns iterator over all Nodes that influence the given sink Node.

Does not return the input node. A CallSite sink will return all of the associated CallArgument nodes.

pub fn influencees( &self, src: impl IntoIterGlobalNodes + Sized, edge_type: EdgeSelection ) -> impl Iterator<Item = GlobalNode> + '_

Returns iterator over all Nodes that are influenced by the given src Node.

Does not return the input node. A CallArgument src will return the associated CallSite.

pub fn marked_nodes( &self, marker: Marker ) -> impl Iterator<Item = GlobalNode> + '_

Returns an iterator over all objects marked with marker.

pub fn get_node_types(&self, node: GlobalNode) -> &[DefId]

👎Deprecated: Use NodeExt::types instead

Get the type(s) of a Node.

pub fn has_marker(&self, marker: Marker, node: GlobalNode) -> bool

👎Deprecated: Use NodeExt::has_marker instead

Returns whether the given Node has the marker applied to it directly or via its type.

pub fn all_nodes_for_ctrl( &self, ctrl_id: Endpoint ) -> impl Iterator<Item = GlobalNode> + '_

Returns all DataSources, DataSinks, and CallSites for a Controller as Nodes.

pub fn srcs_with_type( &self, ctrl_id: Endpoint, t: DefId ) -> impl Iterator<Item = GlobalNode> + '_

Returns an iterator over the data sources within controller c that have type t.

pub fn roots( &self, ctrl_id: Endpoint, edge_type: EdgeSelection ) -> impl Iterator<Item = GlobalNode> + '_

Returns an iterator over all nodes that do not have any influencers of the given edge_type.

pub fn desc(&self) -> &ProgramDescription

Returns the input ProgramDescription.

pub fn otypes(&self, id: TypeId) -> &[TypeId]

Returns all the type alias annotation for a given type

pub fn marked_type(&self, marker: Marker) -> &[DefId]

Return all types that are marked with marker

pub fn any_flows( &self, from: &[GlobalNode], to: &[GlobalNode], edge_type: EdgeSelection ) -> Option<(GlobalNode, GlobalNode)>

Return an example pair for a flow from an source from from to a sink in to if any exist.

pub fn all_controllers(&self) -> impl Iterator<Item = (Endpoint, &SPDG)>

Iterate over all defined controllers

pub fn describe_def(&self, def_id: DefId) -> DisplayDef<'_>

Returns a DisplayDef for the given def_id

pub fn describe_node(&self, node: GlobalNode) -> DisplayNode<'_>

👎Deprecated: Use NodeExt::describe instead

Returns a DisplayNode for the given Node

pub fn inputs_of(&self, call_string: CallString) -> NodeCluster

Return which data is being read from for the modification performed at this location

pub fn outputs_of(&self, call_string: CallString) -> NodeCluster

Return which data is being written to at this location

pub fn node_info(&self, node: GlobalNode) -> &NodeInfo

👎Deprecated: Use NodeExt::info instead

Retrieve metadata about a node.

pub fn instruction_at_node(&self, node: GlobalNode) -> &InstructionInfo

Retrieve metadata about the instruction executed by a specific node.

pub fn successors( &self, node: GlobalNode ) -> impl Iterator<Item = GlobalNode> + '_

👎Deprecated: Use NodeExt::successors instead

Return the immediate successors of this node

pub fn predecessors( &self, node: GlobalNode ) -> impl Iterator<Item = GlobalNode> + '_

👎Deprecated: Use NodeExt::predecessors instead

Return the immediate predecessors of this node

pub fn get_location(&self, node: GlobalNode) -> &Span

👎Deprecated: Use NodeExt::get_location instead

Get the span of a node

impl Context

pub fn named_policy<A>( self: Arc<Self>, name: impl Into<Identifier>, policy: impl FnOnce(Arc<PolicyContext>) -> A ) -> A

Add a policy to the diagnostic context.

See the module level documentation for more information on diagnostic context management.

pub fn named_controller<A>( self: Arc<Self>, id: Endpoint, policy: impl FnOnce(Arc<ControllerContext>) -> A ) -> A

Run the computation in the diagnostic context of this controller

See the module level documentation for more information on diagnostic context management.

pub fn named_combinator<A>( self: Arc<Self>, name: impl Into<Identifier>, computation: impl FnOnce(Arc<CombinatorContext>) -> A ) -> A

Nest another named combinator into the diagnostic context.

See the module level documentation for more information on diagnostic context management.

pub fn controller_contexts( self: &Arc<Self> ) -> impl Iterator<Item = Arc<ControllerContext>>

Iterate over all defined controllers as contexts

Trait Implementations

impl Debug for Context

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl HasDiagnosticsBase for Context

fn record(&self, diagnostic: Diagnostic)

Record a diagnostic message.

fn as_ctx(&self) -> &Context

Access to Context, usually also available via std::ops::Deref.