diff --git a/site/content/docs/guide/_index.md b/site/content/docs/guide/_index.md index 80436591..bc8fe37b 100644 --- a/site/content/docs/guide/_index.md +++ b/site/content/docs/guide/_index.md @@ -22,7 +22,7 @@ by opening an issue on our [issue tracker](https://github.com/mitre/hipcheck/iss - [Why Hipcheck?](@/docs/guide/why.md) - [Key Concepts](@/docs/guide/concepts/index.md) - [How to use Hipcheck](@/docs/guide/how-to-use.md) -- [The Plugin System](@/docs/guide/plugin/index.md) +- [Plugins](@/docs/guide/plugin/index.md) - [Analyses](@/docs/guide/analyses.md) - [Configuration](@/docs/guide/configuration.md) - [Debugging](@/docs/guide/debugging.md) diff --git a/site/content/docs/guide/plugin/for-developers.md b/site/content/docs/guide/plugin/for-developers.md index e49371cc..215100fb 100644 --- a/site/content/docs/guide/plugin/for-developers.md +++ b/site/content/docs/guide/plugin/for-developers.md @@ -1,15 +1,17 @@ --- -title: For Developers +title: Developing Plugins --- -# Creating a New Plugin +# Developing Plugins + +## Creating a New Plugin A Hipcheck plugin is a separate executable artifact that Hipcheck downloads, starts, and communicates with over a gRPC protocol to request data. A plugin's executable artifact is the binary, set of executable program files, Docker container, or other artifact which can be run as a command line interface program through a singular "start command" defined in the plugin's -[manifest file](#plugin-manifest). +manifest file. The benefit of the executable-and-gRPC plugin design is that plugins can be written in any of the many languages that have a gRPC library. One drawback is @@ -19,8 +21,8 @@ target platforms. This can be simplified through the optional use of container files as the plugin executable artifact. Once a plugin author writes their plugin, compiles, packages, and -[distribute](#distributing-your-plugin) it, Hipcheck users can specify the -plugin in their policy file for Hipcheck to fetch and use in analysis. +distribute it, Hipcheck users can specify the plugin in their policy file for +Hipcheck to fetch and use in analysis. ## Plugin CLI @@ -30,8 +32,7 @@ on. The port provided via this CLI argument must be the port the running plugin process listens on for gRPC requests, and on which it returns responses. Once started, the plugin should continue running, listening for gRPC requests -from Hipcheck, until shut down by the Hipcheck process. For information on the -Hipcheck gRPC protocol, see [here](#the-plugin-grpc-protocol). +from Hipcheck, until shut down by the Hipcheck process. ## The Rust SDK @@ -274,13 +275,3 @@ on the returned `PluginServer` instance. This function will not return until the gRPC channel with Hipcheck core is closed. And that's all there is to it! Happy plugin development! - -# The Plugin gRPC Protocol - -# The Query Protocol - -# Distributing Your Plugin - -## Plugin Manifest - -## Plugin Download Manifest diff --git a/site/content/docs/guide/plugin/for-users.md b/site/content/docs/guide/plugin/for-users.md index 28ccbe16..b99ecb0b 100644 --- a/site/content/docs/guide/plugin/for-users.md +++ b/site/content/docs/guide/plugin/for-users.md @@ -1,7 +1,9 @@ --- -title: For Users +title: Using Plugins --- +# Using Plugins + When running Hipcheck, users provide a "policy file", which is a [KDL](https://kdl.dev/)-language configuration file that describes everything about how to perform the analysis. It specifies which top-level plugins to diff --git a/site/content/docs/guide/plugin/index.md b/site/content/docs/guide/plugin/index.md index 578f3338..0091a5ab 100644 --- a/site/content/docs/guide/plugin/index.md +++ b/site/content/docs/guide/plugin/index.md @@ -1,5 +1,5 @@ --- -title: The Plugin System +title: Plugins --- # Introduction @@ -17,7 +17,14 @@ in turn query information from other plugins, which Hipcheck performs on their behalf. The remainder of this section of the documentation is split in two. The [first -section](for-users) is aimed at users. It covers how they can specify analysis +section](for-users) is aimed at users. It covers how they can specify analysis plugins and control the use of their data in producing a pass/fail determination -for a given target. The [second section](for-developers) is aimed at plugin -developers, and explains how to create and distribute your own plugin. \ No newline at end of file +for a given target. The [second section](for-developers) is aimed at plugin +developers, and explains how to create and distribute your own plugin. + + +## Table of Contents + +- [Using Plugins](@/docs/guide/plugin/for-users.md) +- [Developing Plugins](@/docs/guide/plugin/for-developers.md) +- [Policy Expressions](@/docs/guide/plugin/policy-expr.md) diff --git a/site/content/docs/guide/plugin/policy-expr.md b/site/content/docs/guide/plugin/policy-expr.md index 2bc7091f..b5107e52 100644 --- a/site/content/docs/guide/plugin/policy-expr.md +++ b/site/content/docs/guide/plugin/policy-expr.md @@ -1,7 +1,9 @@ --- -Policy Expression Reference +title: Policy Expressions --- +# Policy Expressions + "Policy expressions" are a small expression language in Hipcheck that allows the JSON data output by analysis plugins to be reduced to a boolean pass/fail determination used for scoring. Policy expressions are mostly found in policy @@ -34,14 +36,14 @@ Policy expressions have the following primitive types: #### Datetime -Datetimes use the string format from the `jiff` [crate](), which is a lightly -modified version of ISO8601. A datetime must include a date in the format -`--
`. An optional time in the format `T:[MM]:[SS]` will be -accepted after the date. Decimal fractions of hours and minutes are not allowed; -use smaller time units instead (e.g. `T10:30` instead of `T10.5`). Decimal -fractions of seconds are allowed. The timezone is always internally resolved to -UTC, but you can specify the datetime's original timezone as an an offset from -UTC by including `+{HH}:[MM]` or `-{HH}:[MM]`. +Datetimes use the string format from the `jiff` [crate][jiff], which is a +lightly modified version of ISO8601. A datetime must include a date in the +format `--
`. An optional time in the format `T:[MM]:[SS]` will +be accepted after the date. Decimal fractions of hours and minutes are not +allowed; use smaller time units instead (e.g. `T10:30` instead of `T10.5`). +Decimal fractions of seconds are allowed. The timezone is always internally +resolved to UTC, but you can specify the datetime's original timezone as an an +offset from UTC by including `+{HH}:[MM]` or `-{HH}:[MM]`. #### Span @@ -193,3 +195,5 @@ percentage of elements of an array that pass a filter: This policy expression will check that less than half of the elements in `$` are less than 10. It uses JSON pointers twice, once to get the total element count, again to count the number of elements filtered by the lambda. + +[jiff]: https://crates.io/crates/jiff