Crate paralegal_policy

The query engine and framework for defining paralegal policies.

It provides a state machine for programmatically extracting and parsing a Semantic Program Dependence Graph (SPDG) and provides combinators and queries on this graph for you to compose into policies.

Next we show you the most common workflow, then explain the steps and show you how to customize them to your needs.

SPDGGenCommand::global()
    .run("project/dir/to/analyze")?
    .with_context(|ctx| my_property(ctx))

1. SPDGGenCommand lets you programmatically invoke the SDPG extractor. The ::global() method uses cargo paralegal-flow for this purpose, e.g. a global installation of cargo-paralegal-flow that was performed with cargo install.

   • ::custom() lets you instead pick a different binary to run, for instance from a local installation.
   • .get_command() lets you customize the command, for instance by passing additional arguments such as --debug or --dump.

2. .run(dir) invokes the extractor in dir, returning the path (as a GraphLocation) where the SPDG was written to.

   Re-running this command often is cheap, because rustc skips the execution if there are no changes.

   You may generate the graph manually and skip steps 1 and 2. In this case you can specify the GraphLocation with ::std(), which uses the default graph file name or ::custom() to use a custom file name.

3. .with_context() reads and parses the graph file, then invokes the provided closure with a Context. After the closure returns it automatically invokes RootContext::emit_diagnostics.

For information about how to specify policies see the Context struct.

Note: This crate defines both the interface to the property checkers (via Context) and the implementation of the engine (via GraphLocation::build_context). A future version of this crate should ideally separate those out so property checkers do not need to depend on the checker implementation.

Re-exports

• pub use self::algo::flows_to::CtrlFlowsTo;
• pub use self::algo::flows_to::DataAndControlInfluencees;
• pub use self::diagnostics::CombinatorContext;
• pub use self::diagnostics::Diagnostics;
• pub use self::diagnostics::PolicyContext;
• pub use paralegal_spdg;

Modules

• algo
  Algorithms for querying the graph
• context 🔒
• diagnostics
  Emit messages to the user running a policy.

Macros

• assert_error
  Check the condition and emit a Diagnostics::error if it fails.
• assert_warning
  Check the condition and emit a Diagnostics::warning if it fails.
• loc
  A convenience macro that uses file!, line! and column! to return the string "file:line:column". This can be used to mention policy source locations in policies.

Structs

• Config
  Configuration for the framework
• DisplayDef
  Provide display trait for DefId in a Context.
• GlobalNode
  A globally identified node in an SPDG
• GraphLocation
  A path to a ProgramDescription file from which a Context can be created.
• MarkerTargets
  Collection of entities a particular marker has been applied to
• PolicyReturn
  Result of running a policy
• ProgramDescription
  The annotated program dependence graph.
• RootContext
  Interface for defining policies.
• SPDGGenCommand
  Configuration of the cargo paralegal-flow command.
• Stats
  Statistics about the runtime of the various parts of a policy.

Enums

• EdgeSelection
  Which type of edges should be considered for a given traversal

Traits

• Context
  Actions that behave differently depending on the context
• IntoIterGlobalNodes
  This lets us be agnostic whether a primitive (such as flows_to) is called with a GlobalNode or &NodeCluster.
• NodeExt
  Extension trait with queries for single nodes
• NodeQueries
  Context queries conveniently accessible on nodes

Type Aliases

• DefId
• FunctionId
  The type identifying a function that is used in call sites.
• LocalDefId
• MarkableId
  Identifier for a graph element that allows attaching a marker.
• Marker
  User-defined PDG markers.