Adopt AquaSec Security Solution Workflow

[tmikula-dev]

Feature Description

Feature is implementation of Security workflow called aquasec-night-scan.yml. That workflow should daily fetch repository's AquaSec security alerts and create from them updated GH Issues, that can be taken by developers and mitigated.

Please for complete understanding of the solution read the SOLUTION DOCUMENTATION.
For the implementation see following section Proposed Solution.

Problem / Opportunity

Current pain is that the AquaSec findings are not available for all colleagues, that do not have an expensive AquaSec license. So solving security issues are complicated.

Acceptance Criteria

1. The AquaSec solution is running daily in the CI
2. The repository has created following labels: scope:security, type:tech-debt, epic, sec:adept-to-close
3. The repository has created following GH Action secrets: AQUA_GROUP_ID, AQUA_REPOSITORY_ID, TEAMS_WEBHOOK_URL

Proposed Solution

Prerequisites

To use this solution, make sure your environment meets the following requirements:

• AquaSec API credentials (Key and Secret)
• AquaSec Group ID for authentication
• AquaSec Repository ID (UUID format) for the target scan results
• Required labels in the target repository: scope:security, type:tech-debt, sec:adept-to-close, epic

---

Adding the Workflow

Create a workflow file called .github/workflows/aquasec-night-scan.yml in your repository. A ready-to-copy example is available at this LINK.

The caller workflow delegates to the shared reusable workflow in this repository:

# Example caller workflow – Add this to your repository as .github/workflows/aquasec-night-scan.yml

name: AquaSec Night Scan

on:
  schedule:
    - cron: '23 2 * * *' # PICK SLIGHTLY DIFFERENT TIME, SO ALL SCANS DO NOT TRIGGER AT SAME TIME
  workflow_dispatch:
    inputs:
      dry-run:
        description: 'Simulate without making changes'
        required: false
        type: boolean
        default: false

concurrency:
  group: aquasec-night-scan-${{ github.repository }}
  cancel-in-progress: true

permissions:
  contents: read
  actions: read
  issues: write

jobs:
  scan:
    uses: AbsaOSS/organizational-workflows/.github/workflows/aquasec-scan.yml@v1.1.0 # Should be changed to newest release SHA
    with:
      dry-run: ${{ inputs.dry-run || false }}
      min-severity: 'high' # Only high and critical severity alerts will be promoted to issues. PICK WHAT LEVEL OF SEVERITY ISSUES, YOU WANT TO GENERATE.
      project-number: 42
      project-org: 'my-org'
    secrets:
      AQUA_KEY: ${{ secrets.AQUA_KEY }}
      AQUA_SECRET: ${{ secrets.AQUA_SECRET }}
      AQUA_GROUP_ID: ${{ secrets.AQUA_GROUP_ID }}
      AQUA_REPOSITORY_ID: ${{ secrets.AQUA_REPOSITORY_ID }}
      TEAMS_WEBHOOK_URL: ${{ secrets.TEAMS_WEBHOOK_URL }}

---

Workflow Configuration

Input Parameters

Name	Description	Required	Default
dry-run	Simulate issue management without making changes.	No	false
verbose-logging	Enable verbose logging for the AquaSec scan step.	No	false
project-number	GitHub ProjectV2 number (org-level) for priority sync. Required together with severity-priority-map.	No	0
project-org	GitHub organisation that owns the ProjectV2 board.	No	''
min-severity	Minimum severity level for issue creation. Accepted values: low, medium, high, critical (case-insensitive).	No	'low'

Secrets

Name	Required	Description
AQUA_KEY	Yes	AquaSec API Key credential
AQUA_SECRET	Yes	AquaSec API Secret credential
AQUA_GROUP_ID	Yes	AquaSec Group ID for authentication
AQUA_REPOSITORY_ID	Yes	AquaSec Repository ID (UUID format)
TEAMS_WEBHOOK_URL	No	Microsoft Teams Incoming Webhook URL for notifications

Credentials Configuration

For AbsaOSS / absa-group Organisation:

• AQUA_KEY and AQUA_SECRET are stored as organisation secrets and automatically available to all repositories.
• You only need to configure AQUA_GROUP_ID and AQUA_REPOSITORY_ID as repository secrets.

How to Obtain AquaSec Group ID

Option 1: Via User Management (requires User Management access)

1. Navigate to User Management → Groups in the AquaSec platform.
2. Search for and select your specific group.
3. Click on the group to view its details.
4. The Group ID is displayed at the end of the URL after /groups/.

Option 2: Via JWT Token Inspection

1. Open your browser's Developer Tools and navigate to the Network tab.
2. Reload the AquaSec platform and locate any API request in the Request Headers section.
3. Copy your Authorization Bearer token from the headers.
4. Decode the token using for example jwt.io.
5. In the decoded payload, look for the user_groups_user field containing your accessible Group IDs.

How to Obtain AquaSec Repository ID

1. Navigate to Code Repositories in the AquaSec platform.
2. Use the search bar to filter and locate your repository.
3. Click on the repository name to open its overview page.
4. The Repository ID (UUID format) is displayed in the URL after /repositories/.

Example: https://aquasec.com/repositories/9d93jajb-6c6e-438d-8bef-afb5a12396e5/overview
→ Repository ID: 9d93jajb-6c6e-438d-8bef-afb5a12396e5

---

If you have the repository environment ready as well as stored all the secrets - create a PR and follow these steps:

1. Click on the Actions tab in the repository, where you created a PR.
2. On the left bar, find the AquaSec Night Scan
3. Then on the right side, click on Run workflow and select the dev branch with your PR.
4. Run the workflow with the dry-run FIRST! This will show in the logs, what issues would be created with the summary in the end. You can look at the AquaSec platform website to check, if the sums are the same as they should.
5. Once the PR is merged you can run the live run manually or wait for the night, when the workflow get triggered automatically.

Dependencies / Related

• EPIC: https://github.com/absa-group/cps-qa/issues/170
• PILOT: https://github.com/AbsaOSS/organizational-workflows/blob/master/.github/workflows/aquasec-night-scan.yml
• SOLUTION: https://github.com/AbsaOSS/organizational-workflows

Additional Context

The AbsaOSS/organizational-workflows is supposed to store multiple areas, one of them is Security, which is located in the same named module. There is all AquaSec related logic and documentation.