feat: Add FAA scan action for SSC and FoD modules and integrate it in to CI workflows

fcli-core/fcli-action/src/main/resources/com/fortify/cli/generic_action/actions/zip/ci.yaml

@@ -4,15 +4,23 @@ author: Fortify
 usage:
   header: Run CI pipeline
   description: |
-    This action can be used to run a full, standardized CI pipeline that performs the
-    following activities:
+    This action runs a standardized CI pipeline against either FoD or SSC, depending on
+    whether `FOD_URL` or `SSC_URL` is set. Depending on the configured scan types and
+    options, the pipeline performs the following activities:
 
     * Create & configure SSC application version / FoD release if needed
     * Install ScanCentral Client for packaging
     * Package source code using ScanCentral Client
     * Submit SAST scan request
-    * Wait for SAST scan completion
-    * Perform post-scan activities, like checking security policy outcome, exporting results, ...
+    * Optionally submit DAST scan request using pre-existing SC-DAST scan settings (SSC only)
+    * Optionally run Debricked software composition analysis (SCA) and publish results (SSC only)
+    * Wait for scan completion as configured
+    * Optionally run a Fortify Agentic Analyzer (FAA) scan, using the latest available SAST
+      results as context, and import (FoD) or upload (SSC) the FAA results as a SARIF report
+    * Optionally run an Aviator audit (SSC) or enable Aviator audits in the release
+      settings (FoD), and optionally apply Aviator remediations
+    * Perform configured post-scan activities, such as policy checks, summaries,
+      pull request comments, and result exports
 
     Configuration for this fcli action is done through environment variables; the
     sections below list the environment variables supported by this action.
@@ -112,4 +120,4 @@ steps:
         - run.fcli: 
             ci: ${#actionCmd(ciEnvPrefix, module, 'ci')} "--${module}-session=${sessionName}"
 
-
+

fcli-core/fcli-app/src/main/resources/com/fortify/cli/app/actions/build-time/ci-doc.yaml

@@ -215,7 +215,7 @@ formatters:
               \n* Debug logging for Scancentral Client is disabled; pass --debug on the fcli invocation to enable debug logging.
       - title: Scan Execution
         overview: >-
-          Configure SAST scan execution and waiting behavior for ${productNames.fod}.
+          Configure SAST, FAA scan execution and waiting behavior for ${productNames.fod}.
         vars:
           - names: DO_SAST_SCAN\nSAST_SCAN_EXTRA_OPTS
             desc: >-
@@ -230,6 +230,20 @@ formatters:
               `false` to just kick off any configured scans without waiting for completion. Note that doing so
               will skip any post-scan tasks. The `SAST_WAIT_EXTRA_OPTS` environment variable can be used to pass
               extra options to the fcliCmd:fcli fod sast-scan wait-for: command.
+          - names: DO_FAA_SCAN\nFAA_HOME\nFAA_SCAN_EXTRA_OPTS
+            desc: >-
+              The fcli `ci` action supports running a Fortify Agentic Analyzer (FAA) scan, which is disabled by default.
+              Set `DO_FAA_SCAN` to `true` to enable the FAA scan, which is run through the fcli-provided actionRef:_:faa-scan
+              action. FAA must be pre-installed;
+              the FAA installation is taken from `FAA_HOME` if set, otherwise FAA is looked up in the system `PATH`.
+              \n\nThe latest available SAST scan results for the release are downloaded and passed to FAA for context-aware
+              analysis, allowing FAA to avoid reporting issues already found by SAST. As the `ci` action runs the FAA scan
+              after waiting for SAST scan completion (unless waiting is disabled), this usually includes the results from
+              the SAST scan started by the current pipeline. If no SAST results are available, FAA runs without SAST context.
+              FAA results are imported into ${productNames.fod} as a SARIF report; the `ci` action doesn't wait for this import
+              to be processed.
+              \n\nThe `FAA_SCAN_EXTRA_OPTS` environment variable can be used to pass extra options to the FAA scan action;
+              to pass extra options to the FAA scanner itself, use `FAA_SCAN_EXTRA_OPTS=--extra-scan-opts="<options>"`.
       - title: Post-Scan Actions
         overview: >
           Configure post-scan tasks including release summaries, policy checks, pull request comments, and
@@ -353,7 +367,7 @@ formatters:
               \n* Debug logging for Scancentral Client is disabled; pass --debug on the fcli invocation to enable debug logging.
       - title: Scan Execution
         overview: >-
-          Configure SAST, DAST, and Debricked scan execution and waiting behavior for ${productNames.ssc}.
+          Configure SAST, DAST, Fortify Agentic Analyzer (FAA) and Debricked scan execution and waiting behavior for ${productNames.ssc}.
         vars:
           - names: DO_SAST_SCAN\nSAST_SCAN_EXTRA_OPTS
             desc: >-
@@ -377,7 +391,21 @@ formatters:
               use a custom scan name instead. The `DAST_SCAN_EXTRA_OPTS` environment variable can be used
               to provide additional options to the fcliCmd:fcli sc-dast scan start: command. Note that these
               environment variables only control the submission of the scan request; see the information below
-              for details on waiting for the scan to complete.
+              for details on waiting for the scan to complete. 
+          - names: DO_FAA_SCAN\nFAA_HOME\nFAA_SCAN_EXTRA_OPTS
+            desc: >-
+              The fcli `ci` action supports running a Fortify Agentic Analyzer (FAA) scan, which is disabled by default.
+              Set `DO_FAA_SCAN` to `true` to enable the FAA scan, which is run through the fcli-provided actionRef:_:faa-scan
+              action. FAA must be pre-installed;
+              the FAA installation is taken from `FAA_HOME` if set, otherwise FAA is looked up in the system `PATH`.
+              \n\nThe latest SAST scan results that have been fully processed by ${productNames.ssc} are downloaded and passed
+              to FAA for context-aware analysis, allowing FAA to avoid reporting issues already found by SAST. Note that if the
+              SAST scan started by the current pipeline hasn't been fully processed yet (for example because waiting is disabled
+              or the SAST scan failed), results from an earlier SAST scan will be used. If no processed SAST results are
+              available, FAA runs without SAST context. FAA results are uploaded to ${productNames.ssc} as a SARIF report,
+              and the FAA scan action waits for the uploaded report to be processed unless waiting is disabled through `DO_WAIT`.
+              \n\nThe `FAA_SCAN_EXTRA_OPTS` environment variable can be used to pass extra options to the FAA scan action;
+              to pass extra options to the FAA scanner itself, use `FAA_SCAN_EXTRA_OPTS=--extra-scan-opts="<options>"`.
           - names: DO_DEBRICKED_SCAN\nDEBRICKED_SCAN_EXTRA_OPTS\nDEBRICKED_ACCESS_TOKEN\nDEBRICKED_VERSION\nDEBRICKED_HOME
             desc: >-
               The fcli `ci` action supports running a Debricked Software Composition Analysis (SCA) scan, which
@@ -400,7 +428,8 @@ formatters:
               extra options to the fcliCmd:fcli sc-sast scan wait-for: command, and similarly, the `DAST_WAIT_EXTRA_OPTS`
               environment variable can be used to pass extra options to the fcliCmd:fcli sc-dast scan wait-for: command,
               and the `DEBRICKED_WAIT_EXTRA_OPTS` environment variable can be used to pass extra options to the
-              fcliCmd:fcli ssc artifact wait-for: command.\n\nUnlike other scan types, waiting for DAST scans is disabled
+              fcliCmd:fcli ssc artifact wait-for: command. Waiting for processing of uploaded FAA results is handled
+              by the FAA scan action itself.\n\nUnlike other scan types, waiting for DAST scans is disabled
               by default (as DAST scans are often long-running and only run on demand); set `DO_DAST_WAIT` to `true` to
               wait for DAST scan completion.\n\nDAST scans can take considerably longer than SAST scans, potentially
               exceeding CI/CD job time limits (for example on GitHub Actions or GitLab CI); if the default wait timeout

fcli-core/fcli-fod/src/main/resources/com/fortify/cli/fod/actions/zip/ci.yaml

@@ -3,17 +3,24 @@ author: Fortify
 usage:
   header: Run FoD CI pipeline
   description: |
-    This action can be used to run a full, standardized CI pipeline that performs the
-    following activities:
+    This action runs a FoD CI pipeline with the following activities, depending on
+    the configured options:
 
     * Create & configure FoD application release if needed
     * Package source code
     * Submit SAST scan request
-    * Wait for SAST scan completion
-    * Perform post-scan activities, like checking policy outcome, exporting results, ...
+    * Wait for SAST scan completion as configured
+    * Optionally run Fortify Agentic Analyzer (FAA) and import SARIF results to FoD
+    * Optionally perform Aviator remediation
+    * Perform configured post-scan activities, such as policy checks, summaries,
+      pull request comments, and result exports
 
     Configuration for this fcli action is done through environment variables; the
     sections below list the environment variables supported by this action.
+
+    NOTE: Standard CI integrations use the top-level 'fcli action run ci' action.
+    When invoking this FoD action directly with FAA integration enabled, manually
+    configure the environment variables required by the FAA license check.
 
     ${#include('/ci-action-bootstrap'+(isAsciiDoc?'.adoc':'.txt'))}
 
@@ -65,6 +72,11 @@ steps:
             #fcliCmdSkipFromEnvReason('WAIT', false)
             ?:#fcliCmdSkipFromEnvReason('SAST_WAIT', false) 
         }
+      faa.skipReason: > # Disabled by default; requires DO_FAA_SCAN=true (or FAA_SCAN_ACTION/FAA_SCAN_EXTRA_OPTS) to be enabled
+        ${
+            #actionCmdSkipFromEnvReason('FAA_SCAN', true)
+        }
+
       # Post-scan tasks will be skipped if wait is skipped or if no scans were completed
       # successfully. Post-scan skip reason will be reset to null once the wait task for
       # any scan completed successfully. 
@@ -134,7 +146,17 @@ steps:
           - ${SAST_SCAN.dependencySkipReason}                  # Skip if SAST_SCAN was skipped or failed
         on.success:
           - var.set: { postScan.skipReason: } # Reset postScan.skipReason to allow post-scan tasks to run
-
+
+      # Run FAA scan; SAST context is taken from the latest SAST scan results for the release (if any).
+      # FoD SARIF imports can't be waited for, so FAA results may not yet be reflected by post-scan tasks.
+      FAA_SCAN:
+        cmd: >
+          ${#actionCmd('FAA_SCAN', 'fod', 'faa-scan')}
+          "--source-dir=${global.ci.sourceDir}"
+          "--release=${global.ci.rel}"
+        skip.if-reason:
+          - ${faa.skipReason}                        # Skip if FAA scan is disabled
+
       AVIATOR_REMEDIATIONS:
         cmd: ${#actionCmd('AVIATOR_REMEDIATIONS', 'fod', global.ci.fod_aviatorRemediationsAction)} "--rel=${global.ci.rel}" "--source-dir=${global.ci.sourceDir}" "--progress=none"
         skip.if-reason:

fcli-core/fcli-fod/src/main/resources/com/fortify/cli/fod/actions/zip/faa-scan.yaml

@@ -0,0 +1,117 @@
+# yaml-language-server: $schema=https://fortify.github.io/fcli/schemas/action/fcli-action-schema-dev-2.x.json
+
+author: Fortify
+usage:
+  header: (PREVIEW) Run Fortify Agentic Analyzer Scan
+  description: |
+    This action runs a Fortify Agentic Analyzer (FAA) scan on the project source code
+    and imports the results to FoD as a SARIF report.
+
+    The action automatically downloads the latest SAST scan results for the specified
+    release. FAA uses this context to avoid reporting duplicate issues that were already
+    found by SAST, resulting in higher quality analysis results. If no SAST results are
+    available, FAA runs without SAST context.
+
+    NOTE: SAST context is taken from the latest SAST scan results available in FoD at the
+    time this action runs. If a more recent SAST scan hasn't completed yet, results from an
+    earlier SAST scan will be used. The fcli 'ci' action waits for SAST scan completion
+    (unless waiting is disabled) before running this action. The imported SARIF results are
+    processed asynchronously by FoD; this action doesn't wait for import completion.
+
+config:
+  output: immediate
+  rest.target.default: fod
+  run.fcli.status.log.default: true
+  run.fcli.status.check.default: true
+  mcp: exclude # FAA is a specialized tool requiring specific setup
+
+cli.options:
+  sourceDir:
+    names: --source-dir, -d
+    description: >-
+      Source directory on which to run Fortify Agentic Analyzer scan.
+      Defaults to environment variable `SOURCE_DIR` if not specified.
+    required: false
+    default: ${#env('SOURCE_DIR')}
+  release:
+    names: --release, --rel
+    description: >-
+      FoD release for which to download SAST results and import FAA scan results.
+      Release must already exist in FoD.
+    required: true
+    default: ${#env('FOD_RELEASE')}
+  faaOutput:
+    names: --output, -o
+    description: >-
+      Output SARIF file path where FAA scan results will be written.
+      Defaults to fortifyaa-scan.sarif in the current working directory.
+    required: false 
+    default: fortifyaa-scan.sarif
+  faaPath:
+    names: --faa-path, -p
+    description: >-
+      Path to a pre-installed Fortify Agentic Analyzer (FAA) installation. 
+      FAA must be pre-installed on the system before running this action; 
+      this action only registers the existing installation with fcli.
+      Defaults to the FAA_HOME environment variable.
+      If not specified and FAA_HOME is not set, the system PATH will be searched.
+    required: false 
+    default: ${#env('FAA_HOME')}
+  extraScanOpts:
+    names: --extra-scan-opts
+    description: >-
+      Extra options to be passed to the 'fortifyaa -scan' command.
+    required: false 
+
+steps:
+  - var.set:
+      # Used for passing extra options from ci action without bothering about escaping
+      extraScanOpts: ${#join(" ", {cli.extraScanOpts, global.faaScan?.extraOpts})}
+      sastFprFile: faa_input_${#action.runID().replace('-','_')}.fpr
+      fprArg: ''
+
+  # Register FAA with self-test to fail early if FAA is not found or not properly configured
+  - run.fcli:
+      SETUP_TOOLS:
+        cmd: >-
+          fcli tool env init "--tools=fortifyaa${#isNotBlank(cli.faaPath) ? ':' + cli.faaPath : ''}"
+
+  # Download latest SAST results for the release
+  - run.fcli:
+      DOWNLOAD_LATEST_SAST_FPR:
+        cmd: fcli fod sast-scan download-latest --rel "${cli.release}" -f "${sastFprFile}"
+        status.check: false
+        on.success:
+          - var.set:
+              fprArg: '--fpr "${sastFprFile}"'
+        on.fail:
+          - log.warn:
+              msg: Unable to download latest SAST FPR for release '${cli.release}'; FAA scan will run without SAST context.
+              cause: ${lastException}
+
+  # Run FAA scan with SAST FPR context if available, otherwise run without SAST context
+  - run.fcli:
+      RUN_FAA_SCAN:
+        cmd: >
+          fcli tool fortifyaa run --
+          -clean
+          -scan "${cli.sourceDir}"
+          ${fprArg}
+          -o "${cli.faaOutput}"
+          ${extraScanOpts}
+        stdout: collect
+        stderr: collect
+        on.success:
+          - out.write:
+              stdout: ${RUN_FAA_SCAN.stdout}
+              stderr: ${RUN_FAA_SCAN.stderr}
+        on.fail:
+          - out.write:
+              stdout: ${RUN_FAA_SCAN.stdout}
+              stderr: ${RUN_FAA_SCAN.stderr}
+          - throw: FAA Scan failed with errors.
+      IMPORT_SARIF:
+        cmd: >
+          fcli fod sast-scan import-sarif 
+          --rel "${cli.release}"
+          -f "${cli.faaOutput}"

fcli-core/fcli-ssc/src/main/resources/com/fortify/cli/ssc/actions/zip/ci.yaml

@@ -4,18 +4,26 @@ author: Fortify
 usage:
   header: Run SSC CI pipeline
   description: |
-    This action can be used to run a full, standardized CI pipeline that performs the
-    following activities:
-        
+    This action runs an SSC CI pipeline with the following activities, depending on
+    the configured scan types and options:
+
     * Create & configure SSC application version if needed
     * Package source code
-    * Submit SAST scan request
-    * Submit DAST scan request, using pre-existing SC-DAST scan settings
-    * Wait for SAST/DAST scan completion
-    * Perform post-scan activities, like checking policy outcome, exporting results, ...
+    * Submit SAST scan requests
+    * Optionally submit DAST scan requests using pre-existing SC-DAST scan settings
+    * Optionally run Debricked software composition analysis (SCA) and publish results
+    * Wait for scan completion as configured
+    * Optionally run Fortify Agentic Analyzer (FAA) and upload SARIF results to SSC
+    * Optionally perform Aviator auditing and remediation
+    * Perform configured post-scan activities, such as policy checks, summaries,
+      pull request comments, and result exports
 
     Configuration for this fcli action is done through environment variables; the
     sections below list the environment variables supported by this action.
+
+    NOTE: Standard CI integrations use the top-level 'fcli action run ci' action.
+    When invoking this SSC action directly with FAA integration enabled, manually
+    configure the environment variables required by the FAA license check.
 
     ${#include('/ci-action-bootstrap'+(isAsciiDoc?'.adoc':'.txt'))}
 
@@ -78,13 +86,18 @@ steps:
         ${
             #extraOpts('DEBRICKED_SCAN')
         }
+      faa.skipReason: > # Disabled by default; requires DO_FAA_SCAN=true (or FAA_SCAN_ACTION/FAA_SCAN_EXTRA_OPTS) to be enabled
+        ${
+            #actionCmdSkipFromEnvReason('FAA_SCAN', true)
+        }
+
       aviator.skipReason: > # Enabled if AVIATOR_TOKEN & AVIATOR_URL specified, unless explicitly disabled
         ${
             #fcliCmdSkipFromEnvReason('AVIATOR_AUDIT', false)
             ?:#skipBlankEnvReason('AVIATOR_TOKEN')
             ?:#skipBlankEnvReason('AVIATOR_URL')
         }
-      aviator.loginOpts: --url=AVIATOR_URL
+      aviator.loginOpts: --url=${#env('AVIATOR_URL')}
       aviator.app: ${#env('AVIATOR_APP')?:'::av::application.name'}
       wait.skipReason: >- # Enabled by default, unless explicitly disabled through DO_WAIT or DO_SAST_WAIT (deprecated)
         ${
@@ -199,12 +212,21 @@ steps:
               skip.if-reason:
                 - ${SAST_WAIT.dependencySkipReason}                      # Skip if SAST_WAIT was skipped or failed
                 - ${#isDebugEnabled()?'':'--debug flag not specified'}   # Skip if debugging is disabled
-            DOWNLOAD_SAST_FPR:
-              cmd: "${#fcliCmd('DOWNLOAD_SAST_FPR', 'sc-sast scan download -t fpr')} ::sc_sast_scan::"
+
+            # Run FAA scan; the faa-scan action handles SAST context download, SARIF upload and
+            # waiting for artifact processing (skipped if waiting is disabled for the ci action).
+            FAA_SCAN:
+              cmd: >
+                ${#actionCmd('FAA_SCAN', 'ssc', 'faa-scan')}
+                "--source-dir=${global.ci.sourceDir}"
+                "--app-version=${global.ci.av}"
+                ${#isBlank(wait.skipReason) ? '' : '--skip-wait=true'}
               skip.if-reason:
-                - ${SAST_WAIT.dependencySkipReason}                      # Skip if SAST_WAIT was skipped or failed
-                - ${#isDebugEnabled()?'':'--debug flag not specified'}   # Skip if debugging is disabled
-
+                - ${faa.skipReason}                         # Skip if FAA scan is disabled
+              on.success:
+                - if: ${#isBlank(wait.skipReason)}
+                  var.set: { postScan.skipReason: } # Reset postScan.skipReason to allow post-scan tasks to run
+
             AVIATOR_AUDIT:
               cmd: ${#fcliCmd('AVIATOR_AUDIT', 'aviator ssc audit')} --aviator-session ${sessionName} --av "${global.ci.av}" --app "${aviator.app}" --store aviator_audit
               skip.if-reason: