From d8f5c5fa872601a6c316bd1ce781c747362f9484 Mon Sep 17 00:00:00 2001 From: Mark Michon Date: Mon, 26 Jun 2023 19:46:59 -0700 Subject: [PATCH 1/3] docs: add dataflow guide --- docs/_data/nav.js | 4 ++ docs/docs.md | 1 + docs/guides/dataflow.md | 154 ++++++++++++++++++++++++++++++++++++++++ docs/guides/index.md | 1 + 4 files changed, 160 insertions(+) create mode 100644 docs/guides/dataflow.md diff --git a/docs/_data/nav.js b/docs/_data/nav.js index ed3aebb40..d363b3bd4 100644 --- a/docs/_data/nav.js +++ b/docs/_data/nav.js @@ -20,6 +20,10 @@ module.exports = [ name: "Run a privacy report", url: "/guides/privacy/", }, + { + name: "Run a data flow report", + url: "/guides/dataflow/", + }, { name: "Connect to Bearer Cloud", url: "/guides/bearer-cloud/", diff --git a/docs/docs.md b/docs/docs.md index 288f3af4e..90ece420d 100644 --- a/docs/docs.md +++ b/docs/docs.md @@ -39,6 +39,7 @@ Guides help you make the most of Bearer CLI so you can get up and running quickl - [Set up CI/CD](/guides/ci-setup/) - [Create custom rule](/guides/custom-rule/) - [Run a privacy report](/guides/privacy/) +- [Run a data flow report](/guides/dataflow/) - [Connect to Bearer Cloud](/guides/bearer-cloud/) ## Explanations diff --git a/docs/guides/dataflow.md b/docs/guides/dataflow.md new file mode 100644 index 000000000..c85946db6 --- /dev/null +++ b/docs/guides/dataflow.md @@ -0,0 +1,154 @@ +--- +title: Run a data flow report +--- + +# Run a data flow report + +Bearer CLI's [data flow report type](/explanations/reports/#data-flow-report) + +The data flow report is made up of four sections: + +- Data types: For any data type Bearer detects, the report will display their categories, each instance within the codebase, and associated model and field information if available. +- Risks: For languages that support security report rules, the report will include a `risks` section with information about any findings and their associated location within the codebase. +- Components: Resources such as internal data stores, cloud data stores, and third party APIs are displayed alongside their detection location. +- Dependencies: A list of dependencies detected in package managers, along with their linked version. + +## Getting started + +If you haven't already, install Bearer CLI using the instructions on the [installation page](/reference/installation/) or the [quick start](/quickstart/). + +To run your first data flow report, navigate to the project root and use the `bearer scan` command with the `--report dataflow` flag: + +```bash +bearer scan . --report dataflow +``` + +## Data flow report output + +To get a better sense of what's included in the report, lets look at the output from the `juice-shop` example project. If you're following along, run the following command. + +```bash +bearer scan . --report dataflow --format json +``` + +If you have [jq](https://stedolan.github.io/jq/) installed, it can format the output for your to make it easier to browse. + +```bash +bearer scan . --report dataflow | jq +``` + +Below is an excerpt of the `data_types` portion of the data flow report. It includes the *Email address* data type with specifics on where Bearer CLI detected it. + +```json +{ + "data_types": [ + { + "category_name": "Contact", + "category_groups": ["PII", "Personal Data"], + "name": "Email Address", + "detectors": [ + { + "name": "typescript", + "locations": [ + { + "filename": "data/types.ts", + "full_filename": "data/types.ts", + "start_line_number": 22, + "start_column_number": 3, + "end_column_number": 8, + "field_name": "email", + "object_name": "User", + "subject_name": "User" + }, + ] + } + ] + } + ] +} +``` + +Next, if the codebase [supports rules](/reference/supported-languages/), the report includes risk information based on rule findings. It includes the rule id (`detector_id`), details about the code location, and the content that triggered the rule. + +```json +{ + "risks": [ + { + "detector_id": "javascript_express_exposed_dir_listing", + "locations": [ + { + "full_filename": "data/static/codefixes/accessLogDisclosureChallenge_1_correct.ts", + "filename": "data/static/codefixes/accessLogDisclosureChallenge_1_correct.ts", + "start_line_number": 2, + "start_column_number": 3, + "end_line_number": 2, + "end_column_number": 76, + "source": { + "start_line_number": 2, + "start_column_number": 3, + "end_line_number": 2, + "end_column_number": 76, + "content": "app.use('/ftp', serveIndexMiddleware, serveIndex('ftp', { icons: true }))" + }, + "presence_matches": [ + { + "name": "app.use($\u003c...\u003eserveIndex()$\u003c...\u003e)\n" + } + ] + }, + ] + } + ] +} +``` + +Next, the `components` section contains third party services and local or external datastores. Below, we can see that the project uses an AWS API. Bearer CLI detected it in a configuration file within the codebase. + +```json +{ + "components": [ + { + "name": "Amazon AWS APIs", + "type": "external_service", + "sub_type": "third_party", + "locations": [ + { + "detector": "yaml_config", + "full_filename": "config/oss.yml", + "filename": "config/oss.yml", + "line_number": 36 + } + ] + }, + // ... + ] +} +``` + +Finally, the `dependencies` portion analyzes package details for each language and collects details about a project's installed dependencies. + +```json +{ + "dependencies": [ + { + "name": "@angular-devkit/build-angular", + "version": "15.0.4", + "filename": "frontend/package.json", + "detector": "package-json" + }, + // ... + ] +} +``` + +## Write the report to a file + +You may find the need to write the data flow report to a file for parsing or consumption by other tools. Use the `--output` flag to write the report to a local path. + +```bash +bearer scan . --report dataflow --output output/path/data-flow-report.json +``` + +## Next steps + +For more ways to make the most of our Bearer CLI, see our guide on [configuring the scan](/guides/configure-scan/) and the [commands reference](/reference/commands/). Need additional help? [Open an issue]({{meta.links.issues}}) or join our [Discord community]({{meta.links.discord}}). \ No newline at end of file diff --git a/docs/guides/index.md b/docs/guides/index.md index 35cfb921b..2e8a5f9c3 100644 --- a/docs/guides/index.md +++ b/docs/guides/index.md @@ -11,4 +11,5 @@ Guides help you make the most of Bearer CLI so you can get up and running quickl - [Set up CI/CD](/guides/ci-setup/) - [Create a custom rule](/guides/custom-rule/) - [Run a privacy report](/guides/privacy/) +- [Run a data flow report](/guides/dataflow/) - [Connect to Bearer Cloud](/guides/bearer-cloud/) \ No newline at end of file From f0ae7e28a812a58ef25ed37366dee7befe395f6c Mon Sep 17 00:00:00 2001 From: Mark Michon Date: Mon, 26 Jun 2023 19:57:52 -0700 Subject: [PATCH 2/3] docs: update intro --- docs/guides/dataflow.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/dataflow.md b/docs/guides/dataflow.md index c85946db6..7f72c2628 100644 --- a/docs/guides/dataflow.md +++ b/docs/guides/dataflow.md @@ -4,7 +4,7 @@ title: Run a data flow report # Run a data flow report -Bearer CLI's [data flow report type](/explanations/reports/#data-flow-report) +Bearer CLI's [data flow report type](/explanations/reports/#data-flow-report) provides additional details about the underlying detections and classifications Bearer CLI makes during a scan. It's a good next step if you need more details than the security report offers. The data flow report is made up of four sections: From e9b12ff33a1b85096cc67a4222b60526cc6bb9e7 Mon Sep 17 00:00:00 2001 From: Mark Michon Date: Wed, 28 Jun 2023 07:41:56 -0700 Subject: [PATCH 3/3] Update docs/guides/dataflow.md Co-authored-by: Philip Hayton --- docs/guides/dataflow.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/dataflow.md b/docs/guides/dataflow.md index 7f72c2628..efaeb8e2e 100644 --- a/docs/guides/dataflow.md +++ b/docs/guides/dataflow.md @@ -28,7 +28,7 @@ bearer scan . --report dataflow To get a better sense of what's included in the report, lets look at the output from the `juice-shop` example project. If you're following along, run the following command. ```bash -bearer scan . --report dataflow --format json +bearer scan . --report dataflow ``` If you have [jq](https://stedolan.github.io/jq/) installed, it can format the output for your to make it easier to browse.