From 49a9b476b0829bd7e740773e36c388504dce6fb0 Mon Sep 17 00:00:00 2001 From: Zayan Khan Date: Sun, 26 Jul 2026 19:52:45 -0400 Subject: [PATCH 1/5] docs: fix report screenshot paths in rendered docs Both pages embedded docs/_images/..., which resolves relative to the page's own directory (docs/docs/_images and docs/user-guide/docs/_images respectively) - the image 404s on the MkDocs site and on GitHub. Co-Authored-By: Claude Fable 5 --- docs/index.md | 2 +- docs/user-guide/scan-account.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/index.md b/docs/index.md index 70a019d5..00a815d1 100644 --- a/docs/index.md +++ b/docs/index.md @@ -96,7 +96,7 @@ cloudsplaining scan --exclusions-file exclusions.yml --input-file examples/files It will create an HTML report like [this](https://opensource.salesforce.com/cloudsplaining/): -> ![](docs/_images/cloudsplaining-report.gif) +> ![](_images/cloudsplaining-report.gif) It will also create a raw JSON data file: diff --git a/docs/user-guide/scan-account.md b/docs/user-guide/scan-account.md index 27313959..03b098a4 100644 --- a/docs/user-guide/scan-account.md +++ b/docs/user-guide/scan-account.md @@ -10,7 +10,7 @@ cloudsplaining scan --exclusions-file exclusions.yml --input-file examples/files It will create an HTML report like [this](https://opensource.salesforce.com/cloudsplaining/): -> ![](docs/_images/cloudsplaining-report.gif) +> ![](../_images/cloudsplaining-report.gif) It will also create a raw JSON data file: From 68f98754a1c852c38ad25b5f367889a2f726d391 Mon Sep 17 00:00:00 2001 From: Zayan Khan Date: Sun, 26 Jul 2026 19:52:45 -0400 Subject: [PATCH 2/5] docs: fix broken links to the examples directory examples/ lives at the repository root, so relative links from inside docs/ (docs/examples/...) resolve to nonexistent paths on both GitHub and the docs site; scan-account.md additionally displayed a path (examples/output/example-authz-details-results.json) that has never existed. Link to the canonical GitHub locations. Co-Authored-By: Claude Fable 5 --- docs/index.md | 4 ++-- docs/user-guide/scan-account.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/index.md b/docs/index.md index 00a815d1..e5b08ff3 100644 --- a/docs/index.md +++ b/docs/index.md @@ -101,7 +101,7 @@ It will create an HTML report like [this](https://opensource.salesforce.com/clou It will also create a raw JSON data file: -* `default-iam-results.json`: This contains the raw JSON output of the report. You can use this data file for operating on the scan results for various purposes. For example, you could write a Python script that parses this data and opens up automated JIRA issues or Salesforce Work Items. An example entry is shown below. The full example can be viewed at [examples/files/iam-results-example.json](examples/files/iam-results-example.json) +* `default-iam-results.json`: This contains the raw JSON output of the report. You can use this data file for operating on the scan results for various purposes. For example, you could write a Python script that parses this data and opens up automated JIRA issues or Salesforce Work Items. An example entry is shown below. The full example can be viewed at [examples/files/iam-results-example.json](https://github.com/salesforce/cloudsplaining/blob/master/examples/files/iam-results-example.json) ```json { @@ -126,7 +126,7 @@ It will also create a raw JSON data file: ``` -See the [examples/files](examples/files) folder for sample output. +See the [examples/files](https://github.com/salesforce/cloudsplaining/tree/master/examples/files) folder for sample output. #### Filtering False Positives diff --git a/docs/user-guide/scan-account.md b/docs/user-guide/scan-account.md index 03b098a4..36b7def3 100644 --- a/docs/user-guide/scan-account.md +++ b/docs/user-guide/scan-account.md @@ -15,7 +15,7 @@ It will create an HTML report like [this](https://opensource.salesforce.com/clou It will also create a raw JSON data file: -* `default-iam-results.json`: This contains the raw JSON output of the report. You can use this data file for operating on the scan results for various purposes. For example, you could write a Python script that parses this data and opens up automated JIRA issues or Salesforce Work Items. An example entry is shown below. The full example can be viewed at [examples/output/example-authz-details-results.json](examples/files/iam-results-example.json) +* `default-iam-results.json`: This contains the raw JSON output of the report. You can use this data file for operating on the scan results for various purposes. For example, you could write a Python script that parses this data and opens up automated JIRA issues or Salesforce Work Items. An example entry is shown below. The full example can be viewed at [examples/files/iam-results-example.json](https://github.com/salesforce/cloudsplaining/blob/master/examples/files/iam-results-example.json) ```json { From 811b7917d5118cd4f18a1ac0640d645a1b4efc24 Mon Sep 17 00:00:00 2001 From: Zayan Khan Date: Sun, 26 Jul 2026 19:52:55 -0400 Subject: [PATCH 3/5] docs: fix download/scan command sequence 'download --output' takes an existing directory (click.Path(exists=True), cloudsplaining/command/download.py), not an output filename, and the downloaded file is always named .json - so the documented '--output default-account-details.json' fails and the follow-up scan referenced a file that would never exist. Use the default directory and the real default.json filename. Co-Authored-By: Claude Fable 5 --- docs/report/triage.md | 4 ++-- docs/user-guide/overview.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/report/triage.md b/docs/report/triage.md index 168f5f94..8bbf08d6 100644 --- a/docs/report/triage.md +++ b/docs/report/triage.md @@ -25,11 +25,11 @@ As such, the tool aims to: To recap: you've followed these steps to generate this report: * Downloaded the Account Authorization details JSON file - - `cloudsplaining download --profile default --output default-account-details.json` + - `cloudsplaining download --profile default` * Generated your custom exclusions file - `cloudsplaining create-exclusions-file --output-file exclusions.yml` * Scanned the Account authorization details - - `cloudsplaining scan --input-file default-account-details.json --exclusions-file exclusions.yml` + - `cloudsplaining scan --input-file default.json --exclusions-file exclusions.yml` - This generates two files: (1) The single-file HTML report, and (2) The raw JSON data file ## Triaging workflow diff --git a/docs/user-guide/overview.md b/docs/user-guide/overview.md index 2caad88f..ba449ca0 100644 --- a/docs/user-guide/overview.md +++ b/docs/user-guide/overview.md @@ -14,9 +14,9 @@ You can also specify a custom exclusions file to filter out results that are Fal ## Commands * Download the Account Authorization details JSON file - - `cloudsplaining download --profile default --output default-account-details.json` + - `cloudsplaining download --profile default` * Generate your custom exclusions file - `cloudsplaining create-exclusions-file --output-file exclusions.yml` * Scan the Account Authorization details - - `cloudsplaining scan --input-file default-account-details.json --exclusions-file exclusions.yml` + - `cloudsplaining scan --input-file default.json --exclusions-file exclusions.yml` - This generates two files: (1) The single-file HTML report, and (2) The raw JSON data file From 5ae42ddf0fdd887ef2297a39fe44d5b7d6f1bfd5 Mon Sep 17 00:00:00 2001 From: Zayan Khan Date: Sun, 26 Jul 2026 19:52:55 -0400 Subject: [PATCH 4/5] docs: remove trailing spaces after line-continuation backslashes '\ ' at end of line escapes the space instead of continuing the command, so the multi-line create-multi-account-config-file and scan-multiple-accounts examples break when copy-pasted. Co-Authored-By: Claude Fable 5 --- README.md | 4 ++-- docs/user-guide/scan-multiple-accounts.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 08d974d8..bceb7360 100644 --- a/README.md +++ b/README.md @@ -297,7 +297,7 @@ This diagram depicts how the process works: * First, you'll need to create the multi-account config file. Run the following command: ```bash -cloudsplaining create-multi-account-config-file \ +cloudsplaining create-multi-account-config-file \ -o multi-account-config.yml ``` @@ -325,7 +325,7 @@ Using the data above, you can run the following command: cloudsplaining scan-multi-account \ -c multi-account-config.yml \ --profile scanning-user \ - --role-name CommonSecurityRole \ + --role-name CommonSecurityRole \ --output-bucket my-results-bucket ``` diff --git a/docs/user-guide/scan-multiple-accounts.md b/docs/user-guide/scan-multiple-accounts.md index 77ee4031..5f8bc6f3 100644 --- a/docs/user-guide/scan-multiple-accounts.md +++ b/docs/user-guide/scan-multiple-accounts.md @@ -12,7 +12,7 @@ This diagram depicts how the process works: * First, you'll need to create the multi-account config file. Run the following command: ```bash -cloudsplaining create-multi-account-config-file \ +cloudsplaining create-multi-account-config-file \ -o multi-account-config.yml ``` @@ -42,7 +42,7 @@ Using the data above, you can run the following command: cloudsplaining scan-multi-account \ -c multi-account-config.yml \ --profile scanning-user \ - --role-name CommonSecurityRole \ + --role-name CommonSecurityRole \ --output-bucket my-results-bucket ``` From 83771ce3c6123ec616c8449d60c82e8f23e48c8d Mon Sep 17 00:00:00 2001 From: Zayan Khan Date: Sun, 26 Jul 2026 19:53:12 -0400 Subject: [PATCH 5/5] docs: update contributing guides from make to the just task runner The contributing docs referenced 'make setup-env/test/test-js/build-js/ serve-js/build-docs/serve-docs/generate-report/security-test', but the repository has no Makefile; tooling is uv + just (justfile; test.yml runs 'just unit-tests' etc.). Map each command to its actual recipe and drop the reference to a utils test script that does not exist. Co-Authored-By: Claude Fable 5 --- docs/contributing/documentation.md | 4 ++-- docs/contributing/javascript.md | 6 +++--- docs/contributing/python.md | 8 ++++---- docs/contributing/report.md | 2 +- docs/contributing/testing.md | 12 ++++++------ 5 files changed, 16 insertions(+), 16 deletions(-) diff --git a/docs/contributing/documentation.md b/docs/contributing/documentation.md index b8d498d4..6f4492fa 100644 --- a/docs/contributing/documentation.md +++ b/docs/contributing/documentation.md @@ -20,8 +20,8 @@ python3 -m venv ./venv && source venv/bin/activate uv sync --frozen # Create the HTML files -make build-docs -make serve-docs +just build-docs +just serve-docs # The above will open the built documentation in your browser ``` diff --git a/docs/contributing/javascript.md b/docs/contributing/javascript.md index f89dd9f0..fbf79a5d 100644 --- a/docs/contributing/javascript.md +++ b/docs/contributing/javascript.md @@ -36,7 +36,7 @@ We've already preconfigured several `npm` commands to be run inside the package. # Option 1: npm, as defined in package.json npm run serve # Option 2: Makefile -make serve-js +just serve-js ``` You can then access the application over [http://localhost:8080](http://localhost:8080). @@ -47,7 +47,7 @@ You can then access the application over [http://localhost:8080](http://localhos # Option 1: npm, as defined in package.json npm run test # Option 2: Makefile -make test-js +just test-js ``` * Build the most updated Javascript bundle @@ -56,7 +56,7 @@ make test-js # Option 1: npm, as defined in package.json npm build # Option 2: Makefile -make build-js +just build-js ``` ### Adding new JavaScript utility functions: Checklist diff --git a/docs/contributing/python.md b/docs/contributing/python.md index b7525dbf..3a1f0796 100644 --- a/docs/contributing/python.md +++ b/docs/contributing/python.md @@ -12,26 +12,26 @@ uv sync --frozen ``` -### Makefile +### Just * Python commands: ```bash # Set up your local development environment -make setup-env +uv sync --frozen # Auto format and lint the python code with `ruff` prek run -a # Run unit tests with pytest -make test +just unit-tests ``` * Javascript/UI commands ```bash # Run Javascript unit tests -make test-js +just test-js # Generate the updated Javascript bundle make build-js diff --git a/docs/contributing/report.md b/docs/contributing/report.md index 094d4619..cd70336c 100644 --- a/docs/contributing/report.md +++ b/docs/contributing/report.md @@ -3,7 +3,7 @@ To test the report, run the following from the root directory: ```bash -make generate-report +just generate-report ``` That will generate the example report, without having to go through the full scan. diff --git a/docs/contributing/testing.md b/docs/contributing/testing.md index 1e93fda4..61cdc466 100644 --- a/docs/contributing/testing.md +++ b/docs/contributing/testing.md @@ -2,21 +2,21 @@ ## Local Unit Testing and Integration Testing -We highly suggest that you run all the tests before pushing a significant commit. It would be painful to copy/paste all of those lines above - so we’ve compiled a test script in the utils folder. +We highly suggest that you run all the tests before pushing a significant commit. The [just](https://github.com/casey/just) recipes below are the same ones the GitHub Actions build runs. -Just run this from the root of the repository: +Run them from the root of the repository: ```bash # Run Python unit tests -make test +just unit-tests # Run Javascript unit tests -make test-js +just test-js # Run Python security tests -make security-test +just safety-scan ``` -It will execute all the tests that would normally be run during the GitHub actions build. If you want to see if it will pass the tests in GitHub actions, you can just run that quick command on your machine. +These execute the tests that run during the GitHub Actions build, so if they pass on your machine the CI test jobs should pass too.