angr.state_plugins.plugin

class angr.state_plugins.plugin.SimStatePlugin

Bases: object

This is a base class for SimState plugins. A SimState plugin will be copied along with the state when the state is branched. They are intended to be used for things such as tracking open files, tracking heap details, and providing storage and persistence for SimProcedures.

STRONGREF_STATE = False
__init__()
Return type:

None

state: SimState[Any, Any]
set_state(state)

Sets a new state (for example, if the state has been branched)

Return type:

None

set_strongref_state(state)
Return type:

None

static memo(f)

A decorator function you should apply to copy

Return type:

_CopyFunc[TypeVar(S_co)]

Parameters:

f (Callable[[Any, dict[int, Any]], S_co])

copy(_memo)

Should return a copy of the plugin without any state attached. Should check the memo first, and add itself to memo if it ends up making a new copy.

In order to simplify using the memo, you should annotate implementations of this function with SimStatePlugin.memo

The base implementation of this function constructs a new instance of the plugin’s class without calling its initializer. If you super-call down to it, make sure you instantiate all the fields in your copy method!

Parameters:

  • memo – A dictionary mapping object identifiers (id(obj)) to their copied instance. Use this to avoid infinite recursion and diverged copies.

  • _memo (dict[int, Any])

Return type:

SimStatePlugin

merge(others, merge_conditions, common_ancestor=None)

Should merge the state plugin with the provided others. This will be called by state.merge() after copying the target state, so this should mutate the current instance to merge with the others.

Note that when multiple instances of a single plugin object (for example, a file) are referenced in the state, it is important that merge only ever be called once. This should be solved by designating one of the plugin’s referees as the “real owner”, who should be the one to actually merge it. This technique doesn’t work to resolve the similar issue that arises during copying because merging doesn’t produce a new reference to insert.

There will be n others and n+1 merge conditions, since the first condition corresponds to self. To match elements up to conditions, say zip([self] + others, merge_conditions)

When implementing this, make sure that you “deepen” both others and common_ancestor before calling sub-elements’ merge methods, e.g.

self.foo.merge(
    [o.foo for o in others],
    merge_conditions,
    common_ancestor=common_ancestor.foo if common_ancestor is not None else None
)

During static analysis, merge_conditions can be None, in which case you should use state.solver.union(values). TODO: fish please make this less bullshit

There is a utility claripy.ite_cases which will help with constructing arbitrarily large merged ASTs. Use it like self.bar = claripy.ite_cases(zip(conditions[1:], [o.bar for o in others]), self.bar)

Parameters:

  • others – the other state plugins to merge with

  • merge_conditions – a symbolic condition for each of the plugins

  • common_ancestor – a common ancestor of this plugin and the others being merged

Returns:

True if the state plugins are actually merged.

Return type:

bool

widen(others)

The widening operation for plugins. Widening is a special kind of merging that produces a more general state from several more specific states. It is used only during intensive static analysis. The same behavior regarding copying and mutation from merge should be followed.

Parameters:

others (Iterable[SimStatePlugin]) – the other state plugins to widen with

Returns:

True if the state plugin is actually widened.

Return type:

bool

classmethod register_default(name, xtr=None)
Return type:

None

Parameters:
init_state()

Use this function to perform any initialization on the state at plugin-add time

Return type:

None