turbot · judell · Nov 27, 2024 · Nov 27, 2024 · Nov 27, 2024 · Nov 27, 2024
diff --git a/docs/build/create-mod.md b/docs/build/create-mod.md
@@ -1,6 +1,5 @@
 ---
 title: Creating a Mod
-sidebar_label: Creating a Mod
 ---
 
 # Create a Mod
@@ -35,4 +34,4 @@ mod "powerpipe_demo" {
 
 ```
 
-Your mod is initialized! You can add [dashboards](/docs/powerpipe-hcl/dashboard), [benchmarks](/docs/powerpipe-hcl/benchmark) and other resources to your mod using [Powerpipe HCL](/docs/powerpipe-hcl/). You can even [use resources from other mods](/docs/build/mod-dependencies); explore the available mods on the [Powerpipe Hub](https://hub.powerpipe.io)!
+Your mod is initialized! You can add [dashboards](/docs/powerpipe-hcl/dashboard), [benchmarks](/docs/powerpipe-hcl/benchmark) and other resources to your mod using [Powerpipe HCL](/docs/powerpipe-hcl/). You can even [use resources from other mods](/docs/build/mod-dependencies). Explore the available mods on the [Powerpipe Hub](https://hub.powerpipe.io)!
diff --git a/docs/build/index.md b/docs/build/index.md
@@ -5,7 +5,7 @@ sidebar_label: Build Mods
 # Powerpipe Mods
 
 
-A Powerpipe **mod** is a portable, versioned collection of related Powerpipe resources such as dashboards, benchmarks, queries, and controls. Powerpipe mods and mod resources are defined in HCL, and distributed as simple text files.  Modules can be found on the [Powerpipe Hub](https://hub.powerpipe.io) and may be shared with others from any public git repository. 
+A Powerpipe **mod** is a portable, versioned collection of related Powerpipe resources such as dashboards, benchmarks, queries, controls, and detectionss. Powerpipe mods and mod resources are defined in HCL, and distributed as simple text files.  Modules can be found on the [Powerpipe Hub](https://hub.powerpipe.io) and may be shared with others from any public git repository. 
 
 Mods provide an easy way to share dashboards, benchmarks, and other resources.
 

diff --git a/docs/build/mod-database.md b/docs/build/mod-database.md
@@ -1,6 +1,5 @@
 ---
 title: Setting the Database
-sidebar_label: Setting the Database
 ---
 
 # Setting the Database

diff --git a/docs/build/mod-dependencies.md b/docs/build/mod-dependencies.md
@@ -1,6 +1,5 @@
 ---
 title: Mod Dependencies
-sidebar_label: Mod Dependencies
 ---
 
 # Mod Dependencies

diff --git a/docs/build/mod-variables.md b/docs/build/mod-variables.md
@@ -1,6 +1,5 @@
 ---
 title: Using Variables
-sidebar_label: Using Variables
 ---
 
 # Using Variables

diff --git a/docs/build/param-query.md b/docs/build/param-query.md
@@ -1,6 +1,5 @@
 ---
 title: Passing Parameters
-sidebar_label: Passing Parameters
 ---
 
 # Passing Parameters to Queries & Controls

diff --git a/docs/build/writing-controls.md b/docs/build/writing-controls.md
@@ -1,11 +1,10 @@
 ---
 title: Writing Controls
-sidebar_label: Writing Controls
 ---
 
 # Custom Controls
 
-Powerpipe makes it easy to create your own [controls](/docs/powerpipe-hcl/control) and [benchmarks](/docs/powerpipe-hcl/benchmark).  This allows you to define the controls that are important to *you* and *your organization*, and organize them in a way that reflects your organization's standards and practices.  (Of course, there are controls and benchmarks already available in [mods on the Powerpipe Hub](https://hub.powerpipe.io/) as well if you don't want to write your own).
+Many controls and benchmarks are available in [mods on the Powerpipe Hub](https://hub.powerpipe.io/). But if these don't meet your needs, Powerpipe makes it easy to create your own [controls](/docs/powerpipe-hcl/control) and [benchmarks](/docs/powerpipe-hcl/benchmark) that are important to *you* and *your organization*, and organize them in a way that reflects your organization's standards and practices.  
 
 ## Tutorial
 

diff --git a/docs/build/writing-dashboards.md b/docs/build/writing-dashboards.md
@@ -1,15 +1,14 @@
 ---
 title: Writing Dashboards
-sidebar_label: Writing Dashboards
 ---
 
 # Powerpipe Dashboards
 
 A Powerpipe [dashboard](/docs/powerpipe-hcl/dashboard) uses a combination of HCL and SQL to visualize data in a variety of ways. This *dashboards as code* approach makes it easy to create and combine charts and tables, style them, and make them interactive. Use your favorite text editor, receive immediate feedback as you type, and manage your dashboards on GitHub with all your other code artifacts.
 
-## Tutorial
+## Steampipe tutorial
 
-Let's walk through building a simple dashboard that will introduce the key concepts as we go along.
+Let's walk through building a simple Steampipe-backed dashboard that will introduce the key concepts as we go along.
 
 ### Prerequisites
 For this tutorial, we'll be using [Steampipe](https://steampipe.io) with the [RSS plugin](https://hub.steampipe.io/plugins/turbot/rss):
@@ -278,6 +277,30 @@ dashboard "dashboard_tutorial_containers" {
 
 By wrapping the related components in a `container` we are able to show side-by-side sections while keeping the title+chart together as the page resizes.
 
+## Tailpipe Tutorial
+
+  tbd
+
+  Should Steampipe Tutorial and Tailpipe Tutorial be subcategories? It makes sense to have a tutorial for each, and doing that in this single page would be a lot.
+
+  Either way, there is material common to both, so the structure could be:
+
+```
+  Writing Dashboards
+    Steampipe Tutorial (folder)
+    Tailpipe Tutorial (folder)
+    Chart some data
+    Re-use a chart
+    Layout control
+    Nesting components
+```    
+
 ### Wrap-up
 
 We've only scratched the surface of what's possible here. For the full story on dashboard components and their options please check out the [reference docs](/docs/powerpipe-hcl#dashboards).
+
+
+
+
+
+
diff --git a/docs/build/writing-detections.md b/docs/build/writing-detections.md
@@ -0,0 +1,127 @@
+---
+title: Writing Detections
+---
+
+# Writing Detections
+
+Many detections and benchmarks are available in [mods on the Tailpipe Hub](https://hub.tailpipe.io/). However, if these don't meet your needs, Tailpipe makes it easy to create your own **detections** and **benchmarks** to tailor solutions to *your* organization. These can reflect your specific monitoring and security requirements while integrating seamlessly with your dashboards.
+
+This guide introduces the core concepts for creating detections.
+
+---
+
+## What are Detections?
+
+Detections in Tailpipe serve as queries that analyze logs or other data sources to identify patterns, anomalies, or issues of interest. Detections return **all relevant columns**, providing a complete context for interpretation.
+
+---
+
+## Example Detection
+
+Letâ€™s build a simple detection for monitoring AWS CloudTrail logs.
+
+### Prerequisites
+
+To follow this example, ensure you have:
+
+1. [Download and install Tailpipe](https://tailpipe.io/downloads).
+2. Access to the CloudTrail logs you want to analyze, either locally or via a cloud service.
+3. An active Tailpipe instance with your logs configured as a data source.
+
+---
+
+### Create a Detection
+
+1. **Create a Mod**  
+   Tailpipe resources are packaged into mods. First, [create a mod](https://docs.tailpipe.io/create-mod) to house your detection and benchmarks.
+
+2. **Write a Detection Query**  
+   Create a new file in your mod folder called `unauthorized_access.pp` and add the following code:
+
+   ```hcl
+   detection "unauthorized_access" {
+     title = "Unauthorized Access Attempts"
+
+     sql = <<EOT
+       select
+         event_time,
+         event_source,
+         event_name,
+         user_identity,
+         aws_region,
+         source_ip_address,
+         error_code,
+         request_parameters
+       from
+         cloudtrail_logs
+       where
+         error_code is not null
+         and error_code like '%Unauthorized%'
+       order by
+         event_time desc
+     EOT
+   }
+   ```
+
+   - **Purpose**: This detection identifies unauthorized access attempts by querying `cloudtrail_logs` for events with error codes containing "Unauthorized."
+   - **Query Output**: All columns from `cloudtrail_logs` are returned, offering a complete view of the event, including user identity, source IP, and the full error code.
+
+3. **Run Your Detection**  
+   Use the following command to run the detection:
+
+   ```bash
+   tailpipe detection run unauthorized_access
+   ```
+
+   This outputs the raw query results, which can be piped into a dashboard or further filtered as needed.
+
+---
+
+### Organize Detections in a Benchmark
+
+Benchmarks allow grouping detections logically. For example, letâ€™s add another detection and create a benchmark:
+
+```hcl
+detection "suspicious_ip" {
+  title = "Suspicious IP Activity"
+  sql = <<EOT
+    select
+      event_time,
+      event_source,
+      event_name,
+      source_ip_address,
+      user_identity,
+      aws_region
+    from
+      cloudtrail_logs
+    where
+      source_ip_address in ('192.0.2.1', '203.0.113.5')
+    order by
+      event_time desc
+    EOT
+}
+
+benchmark "security_monitoring" {
+  title = "Security Monitoring"
+  children = [
+    detection.unauthorized_access,
+    detection.suspicious_ip,
+  ]
+}
+```
+
+Run the benchmark to execute all child detections:
+
+```bash
+tailpipe benchmark run security_monitoring
+```
+
+---
+
+### Detections in Dashboards
+
+The unfiltered results from detections make them ideal for dashboards. Users can apply filters dynamically, isolating relevant columns or drilling down into specific events.
+
+---
+
+This guide is a starting point. Explore the [Tailpipe Hub](https://hub.tailpipe.io/) for more examples and best practices to maximize your use of detections and benchmarks.
diff --git a/docs/faq/index.md b/docs/faq/index.md
@@ -1,6 +1,5 @@
 ---
 title:  FAQ
-sidebar_label: FAQ
 ---
 
 # FAQ

diff --git a/docs/guides/index.md.todo b/docs/guides/index.md.todo
@@ -1,6 +1,5 @@
 ---
 title: Guides
-sidebar_label: Guides
 ---
 
 # Guides
diff --git a/docs/learn.md b/docs/learn.md
@@ -1,7 +1,6 @@
 ---
 id: learn
 title: Learn Powerpipe
-sidebar_label: Learn Powerpipe
 slug: /
 ---
 

diff --git a/docs/powerpipe-hcl/benchmark.md b/docs/powerpipe-hcl/benchmark.md
@@ -1,6 +1,5 @@
 ---
 title: benchmark
-sidebar_label: benchmark
 ---
 
 

diff --git a/docs/powerpipe-hcl/control.md b/docs/powerpipe-hcl/control.md
@@ -1,5 +1,5 @@
 ---
-title: control
+title: Control
 sidebar_label: control
 ---
 

diff --git a/docs/powerpipe-hcl/detection.md b/docs/powerpipe-hcl/detection.md
@@ -0,0 +1,93 @@
+---
+title: Detection
+sidebar_label: detection
+---
+
+# detection
+
+**Detections** provide a defined structure and interface for queries against logs collected by Tailpipe. 
+
+Detections use **queries** to gather data. 
+
+remainder TBD
+
+## Example Usage
+
+```hcl
+control "cisv130_2_1_2" {
+  title         = "2.1.2 Ensure S3 Bucket Policy allows HTTPS requests (Manual)"
+  description   = "At the Amazon S3 bucket level, you can configure permissions through a bucket policy making the objects accessible only through HTTPS."
+  documentation = file("docs/cisv130/2_1_2.md")
+  sql           = query.s3_bucket_encryption_in_transit_control.sql
+
+  tags = {
+    cloud_provider = "aws" 
+    framework      = "cis"
+    cis_version    = "v1.3.0"
+    cis_item_id    = "1.4"
+    cis_control    = "4.3"
+    cis_type       = "automated"
+    cis_level      = "1"
+  }
+
+} 
+
+``` 
+
+
+You may run a control from the command line:
+
+```bash
+powerpipe control run cisv130_2_1_2
+```
+
+Controls can be organized into benchmarks.  You can run all controls for a benchmark:
+
+```bash
+powerpipe benchmark run cisv130
+```
+
+## Argument Reference
+| Argument | Type | Optional? | Description
+|-|-|-|-
+| `args` | Map | Optional| A map of arguments to pass to the query. The `args` argument may only be specified for controls that specify the `query` argument. 
+| `database` | String |  Optional| A database [connection reference](/docs/reference/config-files/connection), [connection string](/docs/powerpipe-hcl/query#connection-strings), or [Pipes workspace](/docs/run/workspaces#implicit-workspaces) to query.  If not specified, the [default database](/docs/run#selecting-a-database ) will be used.
+| `description` | String| Optional| A description of the control.
+| `documentation` | String (Markdown)| Optional | A markdown string containing a long form description, used as documentation for the mod on hub.powerpipe.io. 
+| `param` | Block | Optional| A [param](/docs/powerpipe-hcl/query#param) block that defines the parameters that can be passed in to the control's query.  `param` blocks may only be specified for controls that specify the `sql` argument. 
+| `query` | Query Reference | Optional | A reference to a [query](/docs/powerpipe-hcl/query) resource that defines the control query to run.  The referenced query must conform to the control interface - it must return the [required control columns](#required-control-columns).  A control must either specify the `query` argument or the `sql` argument, but not both.
+| `severity`| String | Optional | The potential impact of given control.  Allowed values are `none`,`low`,`medium`,`high`,`critical`. The severity names are taken from the [Common Vulnerability Scoring System version 3.1: Specification Document](https://www.first.org/cvss/specification-document).  This document may be used as guidance for classifying your controls.
+| `--search-path` | String |  Optional| Set a comma-separated list of connections to use as a custom search path for the query
+| `--search-path-prefix` | String |  Optional| Set a comma-separated list of connections to use as a prefix to the current search path for the query.
+| `sql` | String | Required | An SQL string that returns rows that conform to the control interface - it must return the [required control columns](#required-control-columns).  A control must either specify the `query` argument or the `sql` argument, but not both.
+| `tags` | Map | Optional | A map of key:value metadata for the benchmark, used to categorize, search, and filter.  The structure is up to the mod author and varies by benchmark and provider. 
+| `title` | String | Optional | Display title for the control.
+
+
+
+#### Required Control Columns
+
+ALL controls must specify queries that return rows that contain the following standard columns:
+
+| Column | Type | Description
+|-|-|-
+| **status** | String | The control status for this row.  Only the defined [control statuses](#control-statuses) should be used.
+| **reason** | String | A description that details WHY the row has the specified status.  The reason should always be set, even if the control is in an 'ok' state.  It should be a sentence ending with a period.
+| **resource** | String | A unique identifier that identifies the targeted resource for this control check.  Ideally, this should be a ***globally unique identifier*** such as an arn.
+
+
+
+##### Control Statuses
+
+| Status | Description
+|-|-
+| **ok** | The control is compliant for the resource/row.
+| **alarm** | The control is not compliant for the resource/row, and should be remediated.
+| **skip** | This control was not evaluated because Powerpipe was requested to skip it.
+| **info** | This control is not automated.  The control may provide instructions to manually verify, and/or may provide additional context.
+| **error** | Used when an error has occurred in calculating the control state.
+
+
+
+#### Additional Control Columns & Dimensions
+A control's query MUST return the required columns, but it may also return additional columns.  These additional columns are referred to as `dimensions` and can be used to specify additional provider-specific columns that are included in control reports and outputs to provide additional context.  For example, a benchmark that runs controls against AWS resources may specify dimensions for `account_id` and `region` to help locate the evaluated resource.  The `account_id` and `region` columns will be added as dimensions to the control output for any control whose query returns those columns.
diff --git a/docs/powerpipe-hcl/index.md b/docs/powerpipe-hcl/index.md
@@ -1,6 +1,5 @@
 ---
 title: Powerpipe HCL
-sidebar_label: Powerpipe HCL
 ---
 
 # Powerpipe HCL

diff --git a/docs/reference/cli/benchmark.md b/docs/reference/cli/benchmark.md
@@ -1,6 +1,5 @@
 ---
 title: powerpipe benchmark
-sidebar_label: powerpipe benchmark
 ---
 
 

diff --git a/docs/reference/cli/control.md b/docs/reference/cli/control.md
@@ -1,6 +1,5 @@
 ---
 title: powerpipe control
-sidebar_label: powerpipe control
 ---