The Scrutiny Framework provides an extensible plugin based architecture for building security auditing tools for Fuchsia. The primary goal is to have a common base for these tools to prevent code duplication. I encourage you to work through the Getting Started section to get a quick overview of the framework and how you can use it and write your own plugins!
Scrutiny is integrated into the build, so it is easy to extend it to add new static analysers to check platform integrity pre-condition at build time.
To get started you can launch Scrutiny with the command
ffx scrutiny shell. If the tool isn't available on your path you can build it by simply adding:
--with //src/security/scrutiny or
--with //bundles:tools to your fx set command.
When you initially launch Scrutiny you will be greeted with a shell interface. This shell supports history, tab completions etc. The first command you will want to try out in the shell is:
This will list all of the currently available commands in Scrutiny. Each individual command can then be further dug into by using:
With just these two instructions you should be able to get a pretty good idea of the different commands but to see some common workflows check out the
examples directory which contains a selection of Scrutiny scripts (.sc).
Some commonly used workflows can be accessed without using the shell interface directly. These have been integrated into ffx to improve usability:
ffx scrutiny extract package [url] [output]
This command will extract a package from a given url to an output directory. This is very useful if you want to quickly inspect a packages contents without having to resolve all the url to blob merkle mappings.
ffx scrutiny extract zbi [input.zbi] [output] ffx scrutiny extract blobfs [blobfs.blk] [output] ffx scrutiny extract fvm [fvm.blk] [output]
Scrutiny makes it easy to internally inspect common file formats such as the ZBI, a Blobfs block or a Fuchsia volume.
ffx scrutiny verify routes
The Scrutiny data model has built in support for doing static capability flow analysis to verify that capability routes are well-formed. This means you can check that your current build doesn't have any components that are requesting capabilities that are not offered to it.
Scrutiny scripts (.sc) can be run with the
fx scrutiny -s script_name command. This will output the content of your script to the screen as it runs through. To get started try out the following example:
ffx scrutiny shell -s examples/zbi_inspect.sc
This script will extract the ZBI into your /tmp/ and allow you to see some of the inner workings of how the Zircon Boot Image is packaged.
This section of the guide provides a deep overview of the architecture behind the framework which should be useful to anyone looking to build a more complex plugin or who is looking to develop and improve the framework itself.
The core of the framework revolves around the
DataModel and is split into three categories:
DataControllersconsume to analyze the system.
DataModel. This is where the complex analysis of the
DataModeloccurs completely independent of how the underlying data is collected. This provides flexability and compatability even if the underlying system changes.
framework/src/model for the implementation of these three categories.
Plugins take a set of
DataControllers and register them with the
PluginManager. This is the primary interface you will work with when adding new features to the framework. Currently plugins must be built into the core binary.
A Scrutiny plugin has three core functions:
DataCollectorsrequired so that the
DataModelis populated with all the information the
DataControllersneed to service queries.
The abstract interface defined in
framework/src/engine/plugin.rs allows the developer to focus on developing the plugin and can benefit from a shared architecture for integrating their plugin into both a REST service and a DataCollector worker pool.
The REST service provides a way for
DataVisualizers to access
DataControllers over the network through REST JSON. This provides the greatest flexability as
DataVisualizers can be written in any language or framework as long as they can communicate over the network to the Scrutiny service.
The REST service is populated automatically by the
PluginManager. If a
Plugin is registered and loaded and provides a
PluginHook for a
DataController mapped to the namespace “/foo/bar” the REST service will then call that
DataController when the URL “http://localhost:8080/foo/bar” is accessed. It handles passing through the query string which is the HTTP body of the request.
This allows the developer to just work on the plugin and take advantage of the shared infrastructure for hooking into