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:
help
This will list all of the currently available commands in Scrutiny. Each individual command can then be further dug into by using:
help command_name
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:
DataControllers
consume to analyze the system.DataCollectors
.DataModel
. This is where the complex analysis of the DataModel
occurs completely independent of how the underlying data is collected. This provides flexability and compatability even if the underlying system changes.Source: framework/src/model
for the implementation of these three categories.
Plugins take a set of DataCollectors
and 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:
DataController
.DataCollectors
required so that the DataModel
is populated with all the information the DataControllers
need 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 DataVisualizers
.