docs: update docs across jobs, executors, and examples (#13)

Fixes typos and rewrites descriptions and comments across the current
jobs, executors, examples, and scripts.

Author: droguljic

src/examples/git_detect_leaks.yml

@@ -5,6 +5,7 @@ description: |
   up to last commit in a build.
   The base revision should be provided for the most accurate results, while the base branch
   can be overridden if necessary.
+
 usage:
   version: 2.1
   orbs:

src/examples/pnpm_scan.yml

@@ -2,6 +2,7 @@ description: |
   By default, the "scan_dependencies" job checks for production dependencies
   with critical and high severity vulnerabilities.
   There is an option to override the scan command, package manager, and root directory.
+
 usage:
   version: 2.1
   orbs:

src/examples/sast.yml

@@ -4,6 +4,7 @@ description: |
   are scanned, or files scoped to the pull request if a short-lived branch is in question.
   There is an option to scan all files inside a repository, change a base branch,
   and enforce a different set of scan rules.
+
 usage:
   version: 2.1
   orbs:

src/executors/gitleaks.yml

@@ -1,5 +1,5 @@
 description: >
-  A Docker executor using default Gitleaks image based on Alpine Linux.
+  A Docker executor using the official Gitleaks image based on Alpine Linux.
 
 parameters:
   tag:

src/executors/semgrep.yml

@@ -1,5 +1,5 @@
 description: >
-  A Docker executor using official Semgrep image based on Alpine Linux.
+  A Docker executor using the official Semgrep image based on Alpine Linux.
 
 parameters:
   tag:

src/jobs/analyze_code.yml

@@ -1,6 +1,6 @@
 description: >
   Run static analysis, or SAST, to find vulnerabilities in the codebase. Utilizes the Semgrep "scan"
-  command to do the analysis, for details hot it works see https://semgrep.dev/docs/cli-reference.
+  command to do the analysis. For details on usage see https://semgrep.dev/docs/cli-reference.
 
 executor: semgrep
 
@@ -29,7 +29,7 @@ parameters:
     type: string
     default: ''
     description: >
-      The name of the base branch for this scan. Usually some long-lived branch, e.g. default branch.
+      The name of the base branch for this scan. Commonly a long-lived branch, e.g. "main" or "master".
 
 steps:
   - checkout

src/jobs/detect_secrets_dir.yml

@@ -1,23 +1,23 @@
 description: >
-  Detect secrets leak inside a project at the directory level. Uses "gitleaks detect" command
-  to do the scan, for details how it works see https://github.com/gitleaks/gitleaks#usage.
+  Detect secrets leak inside a project at the directory level. Under the hood, the "gitleaks detect"
+  command is utilized. For details on usage see https://github.com/gitleaks/gitleaks#usage.
 
 executor: gitleaks
 
 parameters:
   path:
     type: string
     default: '.'
-    description: Path to the directory to scan.
+    description: The path to the directory to scan.
   config:
     type: string
     default: ''
     description: >
-      Path to the Gitleaks config file. By default tries to load <<paramets.path>>/.gitleaks.toml.
+      The path to the Gitleaks config file. By default, it tries to load "<<parameters.path>>/.gitleaks.toml".
   baseline:
     type: string
     default: ''
-    description: Path to the baseline report, i.e. issues that can be ignorred.
+    description: The path to the baseline report, i.e. issues that can be ignored.
 
 steps:
   - checkout
@@ -28,7 +28,7 @@ steps:
         BASELINE_REPORT: <<parameters.baseline>>
       command: <<include(scripts/export-gitleaks-args.sh)>>
   - run:
-      name: Detect secrets inside directory
+      name: Detect secrets inside the directory
       working_directory: <<parameters.path>>
       environment:
         DIR_PATH: <<parameters.path>>

src/jobs/detect_secrets_git.yml

@@ -1,34 +1,34 @@
 description: >
-  Detect secrets leak inside a project at the repository level. Uses "gitleaks detect" command
-  to do the scan, for details how it works see https://github.com/gitleaks/gitleaks#usage.
+  Detect secrets leak inside a project at the repository level. Under the hood, the "gitleaks detect"
+  command is utilized. For details on usage see https://github.com/gitleaks/gitleaks#usage.
 
 executor: gitleaks
 
 parameters:
   path:
     type: string
     default: '.'
-    description: Path to the root of the Git repository to scan.
+    description: The path to the root of the Git repository to scan.
   config:
     type: string
     default: ''
     description: >
-      Path to the Gitleaks config file. By default tries to load <<paramets.path>>/.gitleaks.toml.
+      The path to the Gitleaks config file. By default, it tries to load "<<parameters.path>>/.gitleaks.toml".
   baseline:
     type: string
     default: ''
-    description: Path to the baseline report, i.e. issues that can be ignorred.
+    description: The path to the baseline report, i.e. issues that can be ignored.
   base_branch:
     type: string
     default: ''
     description: >
-      The name of the base branch for for this scan. Usually some long-lived branch, e.g. default branch.
+      The name of the base branch for this scan. Commonly a long-lived branch, e.g. "main" or "master".
   base_revision:
     type: string
     default: ''
     description: >
-      The hash of the last scanned commit from the prior build. Usually just pass CircleCI's
-      <<pipeline.git.base_revision>> pipeline parameter.
+      The hash of the last scanned commit from the prior build. Usually, pass CircleCI
+      "<<pipeline.git.base revision>>" pipeline parameter.
 
 steps:
   - checkout
@@ -39,7 +39,7 @@ steps:
         BASELINE_REPORT: <<parameters.baseline>>
       command: <<include(scripts/export-gitleaks-args.sh)>>
   - run:
-      name: Detect secrets inside Git repository
+      name: Detect secrets inside the Git repository
       working_directory: <<parameters.path>>
       environment:
         REPO_PATH: <<parameters.path>>

src/jobs/scan_dependencies.yml

@@ -17,8 +17,8 @@ parameters:
     type: string
     default: '.'
     description: >
-      Path to the directory containing package.json file.
-      Not needed when package.json is in the root.
+      Path to the directory containing "package.json" file.
+      Not needed when "package.json" is in the root.
   scan_command:
     type: string
     default: ''
@@ -29,7 +29,7 @@ parameters:
 steps:
   - checkout
   - run:
-      name: Check lockfile
+      name: Check the lockfile
       working_directory: <<parameters.pkg_json_dir>>
       command: <<include(scripts/check-lockfile.sh)>>
   - core/ensure_pkg_manager:

src/scripts/detect-secrets-dir.sh

@@ -1,5 +1,5 @@
 #!/bin/bash
 
 echo "Starting the directory scan at path '$DIR_PATH'"
-echo "Using exported gitleaks args '$GITLEAKS_ARGS'"
+echo "Using exported Gitleaks args '$GITLEAKS_ARGS'"
 eval gitleaks "$GITLEAKS_ARGS" --no-git