feat: #comment adding additional docs

README.md

@@ -2,7 +2,6 @@
 
 - [ASH; The *A*utomated *S*ecurity *H*elper](#ash-the-automated-security-helper)
 - [Description](#description)
-  - [ASH change advisory](#ash-change-advisory)
 - [Supported frameworks](#supported-frameworks)
 - [Prerequisites](#prerequisites)
 - [Getting Started](#getting-started)
@@ -14,6 +13,7 @@
 - [Synopsis](#synopsis)
 - [FAQ](#faq)
 - [Feedback](#feedback)
+- [Contributing](#contributing)
 - [Security](#security)
 - [License](#license)
 
@@ -28,10 +28,6 @@ by providing a fast and easy tool to conduct  preliminary security check as earl
 - It uses light, open source tools to maintain its flexibility and ability to run from anywhere.
 - ASH is cloning and running different open-source tools, such as: git-secrets, bandit, Semgrep, Grype, Syft, nbconvert, npm-audit, checkov, cdk-nag and cfn-nag. Please review the tools [LICENSE](license) before usage.
 
-### ASH change advisory
-
-We are currently working on a re-architecture of ASH targeting a single-container architecture as well as documentation to go along with it.
-
 ## Supported frameworks
 
 The security helper supports the following vectors:

docs/content/tutorials/CI/GitHubActions/.github/workflows/run-ash-scan.yml

@@ -0,0 +1,45 @@
+#
+# This example clones the ASH repo and the repo to be scanned, then runs `ash`
+# against the repo.
+#
+# This will build the ASH container image, run the scan using the built image,
+# and publish the scan results as a build artifact.
+#
+name: ASH SAST Scan
+
+on:
+  push:
+    branches: [ '**' ]
+
+env:
+  ASH_OUTPUT_PATH: ash_output
+
+jobs:
+  containerjob:
+    name: Run ASH Scan
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout ASH
+        uses: actions/checkout@v4
+        with:
+          path: ./automated-security-helper
+          repository: awslabs/automated-security-helper
+          ref: v1.3.3
+      - name: Checkout app repo
+        uses: actions/checkout@v4
+        with:
+          path: ./repo
+      - name: Run ASH scan against repo
+        run: |
+          export PATH="$(pwd)/automated-security-helper:$PATH"
+
+          ash \
+            --source-dir "$(pwd)/repo" \
+            --output-dir "${{ env.ASH_OUTPUT_PATH }}"
+
+      - name: Publish ${{ env.ASH_OUTPUT_PATH }}
+        uses: actions/upload-artifact@v3
+        if: success() || failure()
+        with:
+          name: ${{ env.ASH_OUTPUT_PATH }}
+          path: ${{ env.ASH_OUTPUT_PATH }}

docs/content/tutorials/CI/GitLabCI/.gitlab-ci.yml

@@ -0,0 +1,33 @@
+#
+# This example clones the ASH repo and the repo to be scanned, then runs `ash`
+# against the repo.
+#
+# This will build the ASH container image, run the scan using the built image,
+# and publish the scan results as a build artifact.
+#
+variables:
+  ASH_VERSION:
+    description: The version tag of the awslabs/automated-security-helper repo to clone
+    value: v1.3.3
+
+Run ASH Scan:
+  stage: .pre
+  when: always
+  script:
+    # Clone the ASH repository from GitHub at the desired version
+    - |-
+      git clone https://github.com/awslabs/automated-security-helper.git \
+        ../automated-security-helper \
+        --branch "$ASH_VERSION"
+    # Add the ASH repo path to $PATH so `ash` is available in PATH
+    - export PATH="$(pwd)/../automated-security-helper:$PATH"
+    # Run `ash`.
+    # This will build the ASH container first, then run the scan once built.
+    - |-
+      ash \
+        --source-dir "$(pwd)" \
+        --output-dir "$(pwd)/ash_output"
+  artifacts:
+    paths:
+      - ash_output
+    when: always

docs/content/tutorials/CI/Jenkins/Jenkinsfile

@@ -1,36 +1,29 @@
-#!/usr/bin/env groovy
 /*
-  This example uses the generic `docker run` mechanism to run the ASH container as
-  an executable. This only depends on an OCI image runner being installed on the Jenkins
-  worker node.
-
-  Due to the bind mounts required to mount the `source-dir` and `output-dir`, both
-  directories need to exist prior to the bind mount being created, which is why the
-  inital `mkdir -p "$(pwd)/${{ env.ASH_OUTPUT_PATH }}"` call is made before `docker run`.
-
-  This example, like the others included in this repository, uses an example image
-  tag for the ASH container. This is intended to be replaced with a valid repository and
-  image tag for the ASH container, whether publicly available or one from a private
-  registry hosted within your internal environment.
+#
+# This example clones the ASH repo and the repo to be scanned, then runs `ash`
+# against the repo.
+#
+# This will build the ASH container image, run the scan using the built image,
+# and publish the scan results as a build artifact.
+#
 */
 node {
-  def ASH_IMAGE_REPO = 'myregistry.example.com/automated-security-helper'
-  def ASH_IMAGE_TAG = 'latest'
-  def ASH_OUTPUT_PATH = 'ash_output'
+  def ASH_VERSION = 'v1.3.3'
+
+  git(
+    branch: ASH_VERSION,
+    url: 'https://github.com/awslabs/automated-security-helper.git',
+  )
 
   sh(
     script: """
-      # Create the output folder
-      mkdir -p "$(pwd)/${ASH_OUTPUT_PATH}"
+      # Clone the ASH repository from GitHub at the desired version
+      git clone https://github.com/awslabs/automated-security-helper.git \
+        ../automated-security-helper \
+        --branch "${ASH_VERSION}"
 
       # Run the ASH container image
-      docker run \
-        -v="$(pwd):/src" \
-        -v="$(pwd)/${ASH_OUTPUT_PATH}:/out" \
-        ${ASH_IMAGE_REPO}:${ASH_IMAGE_TAG} \
-        ash \
-        --source-dir /src \
-        --output-dir /out
+      export PATH="$(pwd)/../automated-security-helper:$PATH"
     """
   )
 

docs/content/tutorials/running-ash-in-ci.md

@@ -0,0 +1,37 @@
+## Continuous Integration (CI) Execution
+
+ASH supports running in CI environments as an executable container (e.g. via `docker run`) as well as via Container Job mechanisms, depending on CI platform support.
+
+Within the CI folder, there are multiple examples of running ASH scans in various CI platforms. All examples include the following:
+
+* ASH repository is cloned from GitHub alongside the repository to be scanned.
+* ASH repository directory is added to `$PATH` so that `ash` is available to call directly.
+* `ash` is called to invoke the scan, which performs the following steps:
+    1. Creates the `ash_output` directory if it does not already exist
+    2. Builds the ASH container image
+    3. Runs the ASH scan using the built container image
+    4. Generates the results in the `ash_output` directory
+* Once `ash` is complete, uploads `ash_output` directory as a build artifact.
+
+These examples are meant to show simple implementations that will enable quick integration of ASH
+into an application or infrastructure CI pipeline.
+
+---
+
+Current examples provided by subfolder name:
+
+<!-- * Azure Pipelines (`azure-pipelines.yml`)
+    * Example file shows how to run an ASH scan using Azure Pipelines [ContainerJobs](https://learn.microsoft.com/en-us/azure/devops/pipelines/process/container-phases?view=azure-devops). -->
+* GitHub Actions (`.github/workflows/run-ash.yml`)
+    * Job `containerjob`: Example shows how to run ASH with the ASH image itself used for the job execution. This aligns with the `ContainerJob` approach from Azure Pipelines and presents the `ash` script as a callable in PATH.
+    * Job `dockerrun`: Example shows how to run an ASH scan using generic `docker run` invocation (seen below)
+* GitLab CI (`.gitlab-ci.yml`)
+    * Example file shows how to use the ASH image as the runner image in a GitLab CI job
+<!-- * Jenkins (`Jenkinsfile`)
+    * Example file shows a scripted pipeline that runs an ASH scan using `docker run` with ASH as a containerized executable. -->
+
+### ASH Execution Environment Viability
+
+If you are unsure whether ASH will run in your CI environment or not, the primary requirement is the ability to run Linux containers. This is typically true for most CI platforms, but self-hosted CI agents and enterprise security rules may restrict that ability. If you are unsure whether the CI platform you are using will support it, you can walk through the following flowchart for guidance:
+
+![ASH Execution Environment Viability diagram PNG](CI/ASH%20Execution%20Environment%20Viability.png)