feat(DATAGO-115000): Generic Support for fossa cli flags. Implemented path and config here.

.github/actions/sca/fossa-scan/README.md

@@ -0,0 +1,220 @@
+# FOSSA Scan Action
+
+A GitHub Action that runs FOSSA security and license compliance scanning with configurable parameters.
+
+## Overview
+
+This action uses a JSON-based configuration system (`fossa-params.json`) to dynamically map environment variables to FOSSA CLI flags, making it easy to add new parameters without modifying the action logic.
+
+## Configuration
+
+### Parameter Mapping (`fossa-params.json`)
+
+The action reads parameter definitions from `fossa-params.json`:
+
+```json
+{
+  "parameters": [
+    {
+      "env": "SCA_FOSSA_CONFIG",
+      "flag": "--config",
+      "type": "value",
+      "description": "Path to custom .fossa.yml configuration file",
+      "example": "fossa.config=packages/my-package/.fossa.yml"
+    }
+  ]
+}
+```
+
+**Field Definitions:**
+- `env`: Environment variable name (automatically set by `sca-scan` action)
+- `flag`: FOSSA CLI flag to use
+- `type`: Either `"flag"` (boolean) or `"value"` (requires a value)
+- `description`: Human-readable description
+- `example`: Example usage via `additional_scan_params`
+
+### Parameter Types
+
+#### Type: `flag` (Boolean)
+Only added to CLI if environment variable equals `"true"`.
+
+**Example:**
+```yaml
+additional_scan_params: |
+  fossa.analyze_debug=true
+```
+Generates: `fossa analyze --debug`
+
+#### Type: `value` (String)
+Added to CLI with the provided value if non-empty.
+
+**Example:**
+```yaml
+additional_scan_params: |
+  fossa.config=sam-mongodb/.fossa.yml
+  fossa.path=sam-mongodb
+```
+Generates: `fossa analyze --config sam-mongodb/.fossa.yml --path sam-mongodb`
+
+## Usage
+
+### Basic Usage
+
+```yaml
+- name: FOSSA Scan
+  uses: SolaceDev/solace-public-workflows/.github/actions/sca/sca-scan@main
+  with:
+    scanners: "fossa"
+    fossa_api_key: ${{ secrets.FOSSA_API_KEY }}
+```
+
+### With Custom Parameters
+
+```yaml
+- name: FOSSA Scan (Monorepo Plugin)
+  uses: SolaceDev/solace-public-workflows/.github/actions/sca/sca-scan@main
+  with:
+    scanners: "fossa"
+    additional_scan_params: |
+      fossa.path=sam-mongodb
+      fossa.config=sam-mongodb/.fossa.yml
+      fossa.project=my-plugin
+      fossa.branch=PR
+      fossa.revision=${{ github.sha }}
+    fossa_api_key: ${{ secrets.FOSSA_API_KEY }}
+```
+
+## Available Parameters
+
+| Parameter | Type | FOSSA Flag | Commands | Description |
+|-----------|------|------------|----------|-------------|
+| `fossa.analyze_debug` | flag | `--debug` | `analyze` | Enable debug logging |
+| `fossa.branch` | value | `--branch` | `analyze` | Branch name for tracking |
+| `fossa.revision` | value | `--revision` | `analyze`, `test` | Git commit SHA |
+| `fossa.project` | value | `--project` | `analyze`, `test` | Override project name/ID |
+| `fossa.path` | value | N/A (working directory) | `analyze`, `test` | Base directory to scan from |
+| `fossa.config` | value | `--config` | `analyze`, `test` | Path to `.fossa.yml` (optional if using fossa.path) |
+| `fossa.unpack_archives` | flag | `--unpack-archives` | `analyze` | Unpack and scan archives |
+| `fossa.without_default_filters` | flag | `--without-default-filters` | `analyze` | Disable default filters |
+| `fossa.force_vendored_dependency_rescans` | flag | `--force-vendored-dependency-rescans` | `analyze` | Force rescan vendored deps |
+
+**Commands Column:**
+- `analyze` - Used for the `fossa analyze` command (scans code and uploads results)
+- `test` - Used for the `fossa test` command (checks scan results against policies)
+- Both commands - Parameter is used by both commands
+
+**Special Parameters:**
+- `fossa.path` - Sets the working directory for FOSSA commands. This is not a CLI flag but uses GitHub Actions' `working-directory` to change into the specified directory before running `fossa analyze` and `fossa test`.
+  - **Important:** If you specify `fossa.path`, FOSSA will automatically look for `.fossa.yml` in that directory. You only need `fossa.config` if your config file is in a different location or has a non-standard name.
+  - **Example:** `fossa.path=sam-bedrock-agent` will automatically use `sam-bedrock-agent/.fossa.yml` if it exists.
+
+See [fossa-params.json](./fossa-params.json) for the complete list with examples.
+
+## Adding New Parameters
+
+To add a new FOSSA CLI parameter, follow these steps:
+
+### 1. Update the JSON Configuration
+
+Add an entry to [`fossa-params.json`](./fossa-params.json):
+
+```json
+{
+  "env": "SCA_FOSSA_NEW_PARAM",
+  "flag": "--new-param",
+  "type": "value",
+  "commands": ["analyze", "test"],
+  "description": "Description of what this parameter does",
+  "example": "fossa.new_param=value"
+}
+```
+
+**Field Guide:**
+- `env`: Environment variable name (must start with `SCA_FOSSA_`)
+- `flag`: FOSSA CLI flag (e.g., `--config`, `--path`)
+- `type`: Either `"flag"` (boolean) or `"value"` (requires a value)
+- `commands`: Array of FOSSA commands that support this parameter
+  - `["analyze"]` - Only used for `fossa analyze`
+  - `["test"]` - Only used for `fossa test`
+  - `["analyze", "test"]` - Used for both commands
+- `description`: Human-readable description of the parameter
+- `example`: Usage example via `additional_scan_params`
+
+### 2. Run the Test Suite
+
+Before committing, verify your changes work correctly:
+
+```bash
+cd .github/actions/sca/fossa-scan
+./test-parse-fossa-params.sh
+```
+
+Expected output:
+```
+🧪 FOSSA Parameter Parser Test Suite
+...
+✅ All tests passed!
+```
+
+### 3. (Optional) Add a Test Case
+
+For complex parameters, add a test case to [`test-parse-fossa-params.sh`](./test-parse-fossa-params.sh):
+
+```bash
+test_your_new_parameter() {
+  echo ""
+  echo "Test: Your new parameter"
+
+  export SCA_FOSSA_NEW_PARAM="test-value"
+  export FOSSA_PARAMS_CONFIG="$SCRIPT_DIR/fossa-params.json"
+
+  source "$SCRIPT_DIR/parse-fossa-params.sh"
+  build_fossa_args > /dev/null
+
+  assert_contains "$FOSSA_CLI_ARGS" "--new-param test-value" \
+    "Should include --new-param with value"
+
+  unset SCA_FOSSA_NEW_PARAM FOSSA_CLI_ARGS
+}
+```
+
+Then add `test_your_new_parameter` to the test execution section.
+
+### 4. Update Documentation
+
+Add your parameter to the "Available Parameters" table in this README.
+
+### 5. Commit and Create PR
+
+```bash
+git add fossa-params.json README.md
+git commit -m "feat: Add support for --new-param FOSSA flag"
+```
+
+**That's it!** No code changes to `action.yaml` or `parse-fossa-params.sh` are needed - the JSON configuration is declarative and self-contained.
+
+## Architecture
+
+### Flow Diagram
+
+```
+User Workflow (sca-scan)
+  ↓
+  additional_scan_params: "fossa.config=path/.fossa.yml"
+  ↓
+  Converted to: SCA_FOSSA_CONFIG=path/.fossa.yml
+  ↓
+fossa-scan Action
+  ↓
+  Reads: fossa-params.json
+  ↓
+  Maps: SCA_FOSSA_CONFIG → --config path/.fossa.yml
+  ↓
+  Executes: fossa analyze --config path/.fossa.yml
+```
+
+## Related Documentation
+
+- [FOSSA CLI Documentation](https://github.com/fossas/fossa-cli)
+- [Parent SCA Scan Action](../sca-scan/)
+- [FOSSA Parameter Config](./fossa-params.json)

.github/actions/sca/fossa-scan/action.yaml

@@ -12,53 +12,29 @@ runs:
         echo "Installing FOSSA CLI..."
         curl -H 'Cache-Control: no-cache' https://raw.githubusercontent.com/fossas/fossa-cli/master/install-latest.sh | bash
 
-        SCA_FOSSA_ADDITIONAL_ARGS=""
+        # Use the parameter parser script for analyze command
+        export FOSSA_PARAMS_CONFIG="${GITHUB_ACTION_PATH}/fossa-params.json"
+        source "${GITHUB_ACTION_PATH}/parse-fossa-params.sh"
 
-        #if SCA_FOSSA_ANALYZE_DEBUG is set to true, add --debug to analyze args
-        if [ "${{ env.SCA_FOSSA_ANALYZE_DEBUG }}" == "true" ]; then
-          SCA_FOSSA_ADDITIONAL_ARGS="$SCA_FOSSA_ADDITIONAL_ARGS --debug"
-        fi
-
-        # Set branch parameter if SCA_FOSSA_BRANCH environment variable is provided
-        if [ -n "${{ env.SCA_FOSSA_BRANCH }}" ]; then
-          SCA_FOSSA_ADDITIONAL_ARGS="$SCA_FOSSA_ADDITIONAL_ARGS --branch ${{ env.SCA_FOSSA_BRANCH }}"
-        fi
-
-        # Set revision parameter if SCA_FOSSA_REVISION environment variable is provided
-        if [ -n "${{ env.SCA_FOSSA_REVISION }}" ]; then
-          SCA_FOSSA_ADDITIONAL_ARGS="$SCA_FOSSA_ADDITIONAL_ARGS --revision ${{ env.SCA_FOSSA_REVISION }}"
-        fi
-
-        # Add --unpack-archives if SCA_FOSSA_UNPACK_ARCHIVES is set to true
-        if [ "${{ env.SCA_FOSSA_UNPACK_ARCHIVES }}" == "true" ]; then
-          SCA_FOSSA_ADDITIONAL_ARGS="$SCA_FOSSA_ADDITIONAL_ARGS --unpack-archives"
-        fi
+        # Build analyze args
+        build_fossa_args "analyze"
+        echo "SCA_FOSSA_ADDITIONAL_ARGS=${FOSSA_CLI_ARGS}" >> "$GITHUB_ENV"
 
-        # Add --without-default-filters if SCA_FOSSA_WITHOUT_DEFAULT_FILTERS is set to true
-        if [ "${{ env.SCA_FOSSA_WITHOUT_DEFAULT_FILTERS }}" == "true" ]; then
-          SCA_FOSSA_ADDITIONAL_ARGS="$SCA_FOSSA_ADDITIONAL_ARGS --without-default-filters"
-        fi
-
-        # Add --force-vendored-dependency-rescans if SCA_FOSSA_FORCE_VENDORED_DEPENDENCY_RESCANS is set to true
-        if [ "${{ env.SCA_FOSSA_FORCE_VENDORED_DEPENDENCY_RESCANS }}" == "true" ]; then
-          SCA_FOSSA_ADDITIONAL_ARGS="$SCA_FOSSA_ADDITIONAL_ARGS --force-vendored-dependency-rescans"
-        fi
-
-        echo "SCA_FOSSA_ADDITIONAL_ARGS=${SCA_FOSSA_ADDITIONAL_ARGS}" >> "$GITHUB_ENV"
-
-        # Set up test args with only revision parameter
-        SCA_FOSSA_TEST_ARGS=""
-        if [ -n "${{ env.SCA_FOSSA_REVISION }}" ]; then
-          SCA_FOSSA_TEST_ARGS="--revision ${{ env.SCA_FOSSA_REVISION }}"
-        fi
-        echo "SCA_FOSSA_TEST_ARGS=${SCA_FOSSA_TEST_ARGS}" >> "$GITHUB_ENV"
+        # Build test args
+        build_fossa_args "test"
+        echo "SCA_FOSSA_TEST_ARGS=${FOSSA_CLI_ARGS}" >> "$GITHUB_ENV"
 
         echo "::endgroup::"
 
     - name: Fossa - Scan
       shell: bash
+      working-directory: ${{ env.SCA_FOSSA_PATH || '.' }}
       run: |
         echo "::group::🔍 Fossa Scan"
+        if [ -n "${{ env.SCA_FOSSA_PATH }}" ]; then
+          echo "Scanning from directory: ${{ env.SCA_FOSSA_PATH }}"
+        fi
+
         FOSSA_CMD="fossa analyze"
 
         echo "Running: $FOSSA_CMD $SCA_FOSSA_ADDITIONAL_ARGS"
@@ -68,6 +44,7 @@ runs:
     - name: FOSSA - Scan Wait For Results
       continue-on-error: true
       shell: bash
+      working-directory: ${{ env.SCA_FOSSA_PATH || '.' }}
       run: |
         echo "::group::⏳ Fossa Wait For Results"
         echo "Running: fossa test $SCA_FOSSA_TEST_ARGS"

.github/actions/sca/fossa-scan/fossa-params.json

@@ -0,0 +1,81 @@
+{
+  "$schema": "fossa-params-schema",
+  "description": "FOSSA CLI parameter mappings for the fossa-scan GitHub Action",
+  "version": "2.0.0",
+  "parameters": [
+    {
+      "env": "SCA_FOSSA_ANALYZE_DEBUG",
+      "flag": "--debug",
+      "type": "flag",
+      "commands": ["analyze"],
+      "description": "Enable debug logging during FOSSA analysis",
+      "example": "fossa.analyze_debug=true"
+    },
+    {
+      "env": "SCA_FOSSA_BRANCH",
+      "flag": "--branch",
+      "type": "value",
+      "commands": ["analyze"],
+      "description": "Branch name for FOSSA project tracking",
+      "example": "fossa.branch=main"
+    },
+    {
+      "env": "SCA_FOSSA_REVISION",
+      "flag": "--revision",
+      "type": "value",
+      "commands": ["analyze", "test"],
+      "description": "Git revision/commit SHA for FOSSA tracking",
+      "example": "fossa.revision=abc123"
+    },
+    {
+      "env": "SCA_FOSSA_PROJECT",
+      "flag": "--project",
+      "type": "value",
+      "commands": ["analyze", "test"],
+      "description": "Override project name/ID for FOSSA tracking",
+      "example": "fossa.project=MyOrg_my-project"
+    },
+    {
+      "env": "SCA_FOSSA_CONFIG",
+      "flag": "--config",
+      "type": "value",
+      "commands": ["analyze", "test"],
+      "description": "Path to custom .fossa.yml configuration file",
+      "example": "fossa.config=packages/my-package/.fossa.yml"
+    },
+    {
+      "env": "SCA_FOSSA_UNPACK_ARCHIVES",
+      "flag": "--unpack-archives",
+      "type": "flag",
+      "commands": ["analyze"],
+      "description": "Unpack and scan archive files",
+      "example": "fossa.unpack_archives=true"
+    },
+    {
+      "env": "SCA_FOSSA_WITHOUT_DEFAULT_FILTERS",
+      "flag": "--without-default-filters",
+      "type": "flag",
+      "commands": ["analyze"],
+      "description": "Disable default file filters",
+      "example": "fossa.without_default_filters=true"
+    },
+    {
+      "env": "SCA_FOSSA_FORCE_VENDORED_DEPENDENCY_RESCANS",
+      "flag": "--force-vendored-dependency-rescans",
+      "type": "flag",
+      "commands": ["analyze"],
+      "description": "Force rescanning of vendored dependencies",
+      "example": "fossa.force_vendored_dependency_rescans=true"
+    }
+  ],
+  "notes": [
+    "Parameters are mapped from additional_scan_params (e.g., 'fossa.branch=main') to environment variables (e.g., 'SCA_FOSSA_BRANCH')",
+    "Type 'flag' means boolean - only added if set to 'true'",
+    "Type 'value' means the parameter requires a value and is added if non-empty",
+    "The 'commands' field specifies which FOSSA commands support this parameter: 'analyze' and/or 'test'",
+    "Special parameter: 'fossa.path' sets the working directory for FOSSA commands (not a CLI flag, uses GitHub Actions working-directory)",
+    "If you specify 'fossa.path', FOSSA will automatically look for .fossa.yml in that directory - you only need 'fossa.config' if the config is elsewhere",
+    "Example: fossa.path=sam-bedrock-agent will cd into sam-bedrock-agent and use sam-bedrock-agent/.fossa.yml automatically",
+    "To add a new parameter: add an entry to this file and it will automatically be processed"
+  ]
+}