docs: add comments, docs and links to workflows

WIP add comments to attack action

WIP comment private composite actions

.github/actions/attack/action.yml

@@ -1,5 +1,8 @@
-# TODO: make this composite a standalone action
+# NOTE: this is a composite action
+# it could be a public action if moved to an individual public repo
+# it could be a private action for internal use like this one
 name: Attack container CI
+# those inputs are passed to every individual action
 inputs:
   docker_tag:
     description: "docker tag to attack"
@@ -17,32 +20,41 @@ runs:
   using: composite
   steps:
     #
-    # wapiti
+    # Wapiti
     # emits .wapiti/generated_report/report.html
-    # for now, base default scan
+    # for now, base default scan, can be improved alot: https://github.com/wapiti-scanner/wapiti/blob/master/doc/wapiti.ronn
     - name: Wapiti Scan
+      # I cloned their repo and created the docker image, pushing it to my registry
+      # Then i created a githbu action with nodejs to run the docker image since we need --network=host
       uses: gipo355/vuln-docker-scanners-wapiti-action@6147b708e264ce95171ba8c246f0d84a7e6d718a # v1.0.3
       with:
         target: "http://localhost:8080/tomcat-webapp-boilerplate/app"
         github_token: ${{ inputs.github_token }}
+    # ZAP
+    #
+    # can be improved with rules file and cmd_options
+    # TODO: must check how to add addons and extensions, possibly using a custom docker image
+    #
+    # there is an addon to generate a sarif report https://www.zaproxy.org/docs/desktop/addons/report-generation/report-sarif-json/
+    #
+    # ZAP emits json or creates an issue only using theses cmds
+    # /usrreport_json.json report_md.md report_html.html
+    # /usr/bin/chmod a+w report_json.json report_md.md report_html.html
+    # could do post-processing: create custom action to convert zap json to sarif or use zap sarif addon
+    # check trivy, snyk actions for reference on parsing
     - name: ZAP Scan
       uses: zaproxy/action-full-scan@d2a07475d467566c9a3e3c700f31f47724aa1060 # v0.10.0
       with:
+        # pat for creating issues
         token: ${{ inputs.pat }}
+        # docker name only if not pulling from registry
         # docker_name: ${{ env.TEST_TAG }}
         target: "http://localhost:8080/tomcat-webapp-boilerplate/app"
         # rules_file_name: ".zap/rules.tsv"
         cmd_options: "-aj"
-    # TODO: ZAP emits json or creates an issue only
-    # possibly create an action
-    # /usr/bin/touch report_json.json report_md.md report_html.html
-    # /usr/bin/chmod a+w report_json.json report_md.md report_html.html
-    # TODO: post-processing: create custom action to convert zap json to sarif
-    # check trivy, snyk actions for reference on parsing
     #
     # run custom container with nmap
-    # TODO: add  self actions: finish nmap
-    # WARN: can't use docker action with scanners
+    # NOTE: can't use docker action with scanners
     # docker actions don't pass the --network=host  flag
     # must create node action to run docker container
     # check zap action for reference
@@ -61,30 +73,31 @@ runs:
     #     flags: "-sV"
     #     generate_reports: true
     #
-    # init scanning for vulnerabilities
+    # SNYK
     - name: Set up Snyk CLI to check for security issues
       uses: snyk/actions/setup@d406fd286b663eb8c6f8adcced4f7bcd199c0a3f
     - name: login to snyk
       shell: bash
       run: snyk auth ${{ inputs.snyk_token }}
-      # FIXME: sarif output doesn't work
-      # TODO: post-processing the snyk report to remove nulls
-      #
-      # Error: Code Scanning could not process the submitted SARIF file:
-      # could not convert rules: invalid security severity value, is not a number: null
-      # ConfigurationError: Code Scanning could not process the submitted SARIF file:
-      # could not convert rules: invalid security severity value, is not a number: null
-      #     at run (/home/runner/work/_actions/github/codeql-action/f079b8493333aace61c81488f8bd40919487bd9f/lib/upload-sarif-action.js:70:15)
-      #     at async runWrapper (/home/runner/work/_actions/github/codeql-action/f079b8493333aace61c81488f8bd40919487bd9f/lib/upload-sarif-action.js:84:9)
-      #
-      #   # Snyk can be used to break the build when it detects vulnerabilities.
-      #   # In this case we want to upload the issues to GitHub Code Scanning
+    # SNYK CONTAINER
+    # Snyk can be used to break the build when it detects vulnerabilities.
+    # In this case we want to upload the issues to GitHub Code Scanning
+    # BUG: sarif output doesn't work, github code scanning can't process it, nulls in the output
+    # TODO: post-processing the snyk report to remove nulls using a custom action
+    #
+    # Error: Code Scanning could not process the submitted SARIF file:
+    # could not convert rules: invalid security severity value, is not a number: null
+    # ConfigurationError: Code Scanning could not process the submitted SARIF file:
+    # could not convert rules: invalid security severity value, is not a number: null
+    #     at run (/home/runner/work/_actions/github/codeql-action/f079b8493333aace61c81488f8bd40919487bd9f/lib/upload-sarif-action.js:70:15)
+    #     at async runWrapper (/home/runner/work/_actions/github/codeql-action/f079b8493333aace61c81488f8bd40919487bd9f/lib/upload-sarif-action.js:84:9)
+    #
     - name: run snyk container
       shell: bash
       run: snyk container test ${{ inputs.docker_tag }} --file=Dockerfile --sarif > snyk-container.sarif || true
-      # - name: display json output
-      #   shell: bash
-      #   run: cat snyk-container.sarif
+      #
+      # UPLOADS TO GITHUB CODE SCANNING
+      # Will be done when sarifs are fixed
       # - name: Upload snyk container result to GitHub Code Scanning
       #   uses: github/codeql-action/upload-sarif@f079b8493333aace61c81488f8bd40919487bd9f # v3
       #   with:
@@ -94,9 +107,9 @@ runs:
       #   with:
       #     sarif_file: nmap-reports/vulner/vulner-report.sarif
 #
-# TODO: add load test, wapiti, and other scanners
+# TODO: add load test with wrk, and other scanners?
 #
-# TODO: how to scan? on PR? on release?
+# NOTE: must decide where and how to scan. PR, release, schedule, push, etc
+# should it block the build or PR? this is quite hard to do since it's an async process and decisions must be human made
 #
-# pen test and put comment in pr with the results now using PR image
-# we will replicate the pen test with cron on another action on the dev branch tag released image
+# NOTE: where to put outputs? GH pages, github code scanning, PR comments, issues, external applicaton etc

.github/actions/build-run-testcontainer/action.yml

@@ -1,3 +1,5 @@
+# Composite private action to build, run and test a Docker container
+# Will have to respond to the health check endpoint
 name: Build, Run and Test Docker Container
 inputs:
   load:
@@ -23,6 +25,7 @@ runs:
         push: ${{ inputs.push }}
         context: .
         file: ./Dockerfile
+        # load the image into the docker cache to be able to run it
         load: ${{ inputs.load }}
         platforms: linux/amd64
         tags: ${{ inputs.docker_tag }}

.github/actions/ci-setup/action.yml

@@ -1,3 +1,5 @@
+# Composite private action to setup the CI environment with all the tools needed for the project.
+# We could install pre-commit too here
 name: Setup CI
 runs:
   using: composite

.github/actions/docker-setup/action.yml

@@ -1,3 +1,4 @@
+# Privatte composite action to prepare the CI environment for docker with caching and buildx
 name: Setup DOCKER
 runs:
   using: composite

.github/workflows/codeql.yml

@@ -12,6 +12,13 @@ jobs:
     name: Analyze (${{ matrix.language }})
     runs-on: ${{ (matrix.language == 'swift' && 'macos-latest') || 'ubuntu-latest' }}
     timeout-minutes: ${{ (matrix.language == 'swift' && 120) || 360 }}
+    concurrency:
+      # use case: for example, when someone pushes a commit to a PR, the workflow will be triggered again
+      # we want to cancel previous jobs and only run the latest one
+      # TODO: check if this is the correct group to do this
+      # github.ref is the branch name
+      group: ${{ github.workflow }}-${{ github.ref }}
+      cancel-in-progress: true
     permissions:
       security-events: write
       packages: read
@@ -46,3 +53,5 @@ jobs:
         uses: github/codeql-action/analyze@2e230e8fe0ad3a14a340ad0815ddb96d599d2aff # v3
         with:
           category: "/language:${{matrix.language}}"
+          # we don't want to upload security vulns for code that is not merged yet
+          upload: ${{ github.event_name != 'pull_request' }}

.github/workflows/debugging-dumps.yml

@@ -0,0 +1,11 @@
+on:
+  push:
+  pull_request:
+jobs:
+  dump-event:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Dump GitHub context
+        env:
+          GITHUB_CONTEXT: ${{ toJson(github) }}
+        run: echo "$GITHUB_CONTEXT"

.github/workflows/gradle-check-build.yml

@@ -1,12 +1,22 @@
-name: Gradle Check and Build Workflow
+name: Check Test Build Workflow
 on:
   # FIXME: secrets not available from pull_request forks
   pull_request:
     branches:
       - "dev"
   workflow_dispatch: {}
 jobs:
+  # we don't need windows as the container runs on linux only
+  # tomcat image doesn't have a windows version
   build-linux:
+    concurrency:
+      # use case: for example, when someone pushes a commit to a PR, the workflow will be triggered again
+      # we want to cancel previous jobs and only run the latest one
+      # since the job will run in the pull request branch, we can use the branch name to limit concurrency for a single feat branch
+      # to prevent running too many jobs if commits are pushed to the same branch
+      # github.ref is the branch name
+      group: ${{ github.workflow }}-${{ github.ref }}
+      cancel-in-progress: true
     env:
       # required for local testing without risking pulling the wrong image
       TEST_TAG: gipo999/tomcat-webapp-boilerplate:test
@@ -16,26 +26,31 @@ jobs:
       issues: write
       actions: read
       contents: read
+    # don't run the job if the PR is a draft to save resources
     if: github.event.pull_request.draft == false
     name: Lint and Build on Linux Job
     runs-on: ubuntu-latest
     steps:
       - name: Checkout sources Step
         uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29 # v4
+      # setup the CI environment using a private composite action
       - name: Setup CI environment
         uses: ./.github/actions/ci-setup
-        # run the gradle check and build tasks
-      - name: Build with Gradle Wrapper Step
-        # buildWar runs check, test, war tasks
+        # run the gradle check, test, war tasks
         # at this point we won't know if the app will run in a container
+      - name: Build with Gradle Wrapper Step
         run: ./gradlew buildWar
+        # coverage reports in PR comment if modified
       - name: Upload coverage to Codecov
         uses: codecov/codecov-action@125fc84a9a348dbcf27191600683ec096ec9021c # v4.4.1
         with:
           token: ${{ secrets.CODECOV_TOKEN }}
+      # prepare docke environment with caching of images and buildx
       - name: Setup DOCKER environment
         uses: ./.github/actions/docker-setup
       # test the docker image
+      # Using a private composite action to build, run and test the container
+      # uses curl to verify the container is running and /health is responding
       - name: Build, run and test container
         uses: ./.github/actions/build-run-testcontainer
         with:

.github/workflows/publish-docker.yml

@@ -105,7 +105,9 @@ jobs:
           # in docker, labels are needed to store metadata about the image and for provenance
           labels: ${{ steps.meta.outputs.labels }}
     #
-    # TODO: provenance
+    #
+    # this  may not be needed. Looks like as default build-push-action already does this
+    # https://docs.docker.com/build/ci/github-actions/attestations/
     # - name: Generate artifact attestation
     #   uses: actions/attest-build-provenance@v1
     #   with:

.github/workflows/releaser.yml

@@ -27,6 +27,7 @@ jobs:
           persist-credentials: false # <<<--- This line is needed for security
       - uses: ./.github/actions/ci-setup
         name: Setup CI environment
+      # build javadoc and war to add them to the release as assets (must be zipped)
       - name: Build Javadoc with Gradle Wrapper Step
         run: ./gradlew javadoc
       - name: Build War with Gradle Wrapper Step

.github/workflows/semgrep.yml

@@ -6,16 +6,24 @@ on:
     branches:
       - dev
   schedule:
-    - cron: 11 2 * * *
+    - cron: 11 2 * * * # Run every day at 2:11 UTC
 name: Semgrep Workflow
 jobs:
   semgrep:
+    concurrency:
+      # use case: for example, when someone pushes a commit to a PR, the workflow will be triggered again
+      # we want to cancel previous jobs and only run the latest one
+      # TODO: check if this is the correct group to do this
+      # github.ref is the branch name
+      group: ${{ github.workflow }}-${{ github.ref }}
+      cancel-in-progress: true
     permissions:
       security-events: write
       packages: read
       actions: read
       contents: read
-    if: github.event.pull_request.draft == false && github.actor != 'dependabot[bot]'
+    # don't run on draft PRs or dependabot PRs or renovate PRs
+    if: github.event.pull_request.draft == false && github.actor != 'dependabot[bot]' && github.actor != 'renovate[bot]'
     name: Semgrep Job
     runs-on: ubuntu-latest
     env:
@@ -24,9 +32,11 @@ jobs:
       image: semgrep/semgrep@sha256:550dfdac1ec5d4a757d1c2ac0197a6360ef3ac8e3d0a804731eab07242e91b4c
     steps:
       - uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29 # v4
+      # generate the SARIF file to upload to the GitHub Advanced Security Dashboard
       - run: semgrep ci --sarif > semgrep.sarif
       - name: Upload SARIF file for GitHub Advanced Security Dashboard
         uses: github/codeql-action/upload-sarif@2e230e8fe0ad3a14a340ad0815ddb96d599d2aff # v3
         with:
           sarif_file: semgrep.sarif
-        if: always()
+          # we don't want to upload security vulns for code that is not merged yet
+        if: ${{ github.event_name != 'pull_request' }}

.github/workflows/snyk.yml

@@ -1,6 +1,14 @@
 # IMP: snyk token can't be used from forks, so PRs from forks will fail
 name: Snyk Security Scan Workflow
 on:
+  # WARN: secrets not available from pull_request forks
+  #
+  # we can't run this on PRs from forks as snyk token can't be used from forks
+  # for security reasons, prs from forks are not allowed to use/read secrets
+  #
+  # Another note: the generated sarif can be uploaded to the GitHub Code Scanning dashboard
+  # but we don't want to upload security vulns for code that is not merged yet
+  #
   # pull_request:
   #   branches: ["dev"]
   push:

.github/workflows/stale.yml

@@ -1,11 +1,10 @@
 name: Close stale issues and PR Workflow
 on:
   schedule:
-    - cron: "30 1 * * *"
+    - cron: "30 1 * * *" # every day at 1:30am
 jobs:
   stale:
     name: Close stale issues and PR job
-    if: github.event.pull_request.draft == false
     runs-on: ubuntu-latest
     steps:
       - uses: actions/stale@28ca1036281a5e5922ead5184a1bbf96e5fc984e # v9