Skip to content

Commit efcc8fe

Browse files
lindycoderlindycoder
authored
BST-18083 Add base documentation and tests for the scan tests (#267)
Future changes will add the scans to the github actions, this is just documentation Tests have been added to trify-fs and trivy-image so that tests can be validated to work
1 parent a348506 commit efcc8fe

File tree

9 files changed

+689
-0
lines changed

9 files changed

+689
-0
lines changed

‎README.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,3 +17,25 @@
1717
### [CodeQL](scanners/boostsecurityio/codeql)
1818

1919
### [GitLeaks](scanners/boostsecurityio/gitleaks)
20+
21+
## Scanner Testing
22+
23+
The registry includes automated testing for scanners. When a scanner is modified in a pull request, tests are automatically run across multiple CI/CD providers.
24+
25+
### Overview
26+
27+
- **Test Definition**: Each scanner can define tests in a `tests.yaml` file
28+
- **Automatic Detection**: Modified scanners are detected and tested on PR
29+
- **Multi-Provider**: Tests run on GitHub Actions, GitLab CI, Azure DevOps, and Bitbucket
30+
31+
### Documentation
32+
33+
- [Setting Up Tests](docs/setup-tests.md) - How to write tests for your scanner
34+
- [Authentication Strategy](docs/authentication-strategy.md) - OAuth2/OIDC token architecture
35+
36+
#### Test Runner Setup (per CI/CD provider)
37+
38+
- [GitHub Actions](docs/setup-github.md)
39+
- [GitLab CI](docs/setup-gitlab.md)
40+
- [Azure DevOps](docs/setup-azure-devops.md)
41+
- [Bitbucket Pipelines](docs/setup-bitbucket.md)

‎docs/authentication-strategy.md‎

Lines changed: 109 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,109 @@
1+
# CI/CD Test Runner Authentication Strategy
2+
3+
## Executive Summary
4+
5+
Migration from long-lived user tokens to short-lived OAuth2/OIDC tokens across all CI/CD platforms for the scanner registry test orchestration system.
6+
7+
---
8+
9+
## Authentication Solution
10+
11+
| Platform | Auth Method | Token Lifetime | User-Independent |
12+
|------------------|---------------------------|----------------|------------------|
13+
| **GitHub** | GitHub App | 1 hour | ✅ |
14+
| **GitLab** | OAuth2 Application | 2 hours | ✅ |
15+
| **Azure DevOps** | OIDC (Federated Identity) | ~1 hour | ✅ |
16+
| **Bitbucket** | OAuth2 Consumer | 2 hours | ✅ |
17+
18+
### Architecture Flow
19+
20+
```
21+
Scanner Registry PR Created
22+
↓
23+
GitHub Actions Workflow Triggered
24+
↓
25+
┌────────────────────────────────────┐
26+
│ Token Generation (in GH Actions) │
27+
│ - GitHub: Official Action │
28+
│ - GitLab: OAuth2 API call │
29+
│ - Azure: OIDC (no secrets) │
30+
│ - Bitbucket: OAuth2 API call │
31+
└────────────────────────────────────┘
32+
↓
33+
Short-lived tokens (1-2 hours)
34+
↓
35+
Passed to test-action CLI
36+
↓
37+
Trigger test pipelines on each platform
38+
↓
39+
Tokens expire automatically
40+
```
41+
42+
### Key Security Improvements
43+
44+
- ✅ **Short-lived tokens** - Auto-expire in 1-2 hours (vs. indefinite)
45+
- ✅ **No manual rotation** - Tokens generated fresh on each run
46+
- ✅ **Application-based** - Not tied to user accounts
47+
- ✅ **Principle of least privilege** - Minimal scopes (trigger pipelines + read status)
48+
- ✅ **Secrets isolation** - Client credentials stored only in GitHub Actions, never in test-action
49+
- ✅ **Zero secrets for Azure** - OIDC federated identity eliminates client secret storage entirely
50+
- ✅ **Industry standard** - OAuth2/OIDC protocols used by all platforms
51+
52+
---
53+
54+
## Rejected Alternatives
55+
56+
**Managed Identities (Azure)** - Only works if test-action runs inside Azure infrastructure; not applicable for GitHub Actions execution.
57+
58+
**Service Principal with Client Secret (Azure)** - Requires storing `AZURE_CLIENT_SECRET` in GitHub Actions; OIDC federated identity is more secure as it eliminates secret storage entirely.
59+
60+
**Repository/Workspace Access Tokens (Bitbucket)** - Cannot trigger or read pipeline status; insufficient permissions for use case.
61+
62+
**OIDC for GitHub API** - OIDC is for external services authenticating to GitHub, not for GitHub Actions triggering other GitHub workflows; GitHub Apps are the correct solution.
63+
64+
---
65+
66+
## Implementation Requirements
67+
68+
### One-Time Setup (per platform)
69+
70+
1. **GitHub**: Register GitHub App with `contents: read`, `actions: write` permissions
71+
2. **GitLab**: Create OAuth2 Application with `api` scope
72+
3. **Azure DevOps**: Register Microsoft Entra ID application, add federated credential for GitHub Actions OIDC, grant Build (Read & Execute) to Azure DevOps project
73+
4. **Bitbucket**: Create OAuth2 Consumer with `pipeline`, `pipeline:write`, `repository` scopes
74+
75+
### Secrets Configuration
76+
77+
Store client credentials in GitHub Actions repository secrets:
78+
- `GH_APP_ID`, `GH_APP_PRIVATE_KEY`
79+
- `GITLAB_CLIENT_ID`, `GITLAB_CLIENT_SECRET`
80+
- `AZURE_TENANT_ID`, `AZURE_CLIENT_ID` (no client secret - uses OIDC; no subscription needed for Azure DevOps API)
81+
- `BITBUCKET_CLIENT_ID`, `BITBUCKET_CLIENT_SECRET`
82+
83+
### Code Changes
84+
85+
- **GitHub Actions workflow**: Add token generation steps (GitHub App action, OAuth API calls, azure/login with OIDC)
86+
- **GitHub Actions permissions**: Add `id-token: write` permission for Azure OIDC
87+
- **test-action CLI**: Accept `--{platform}-token` arguments instead of client credentials
88+
- **Providers**: Use provided tokens directly instead of generating them
89+
90+
---
91+
92+
## Security Benefits Summary
93+
94+
| Metric | Before | After | Improvement |
95+
|-----------------|-----------------|---------------------|------------------------|
96+
| Token Lifetime | Indefinite | 1-2 hours | **99%+ reduction** |
97+
| Manual Rotation | Required | None | **Zero maintenance** |
98+
| User Dependency | Yes (4 users) | No (4 apps) | **Zero bus factor** |
99+
| Token Scope | Over-privileged | Minimal | **Least privilege** |
100+
| Audit Trail | User actions | Application actions | **Better attribution** |
101+
102+
---
103+
104+
## Compliance & Standards
105+
106+
- ✅ **OAuth 2.0 / OpenID Connect** - Industry standard protocols (RFC 6749, RFC 7519)
107+
- ✅ **Zero Trust** - Short-lived credentials, continuous verification
108+
- ✅ **NIST SP 800-63B** - Authenticator assurance level via cryptographic proof
109+
- ✅ **SOC 2 / ISO 27001** - Automated credential lifecycle management

‎docs/setup-azure-devops.md‎

Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
1+
# Azure DevOps Test Runner Setup
2+
3+
## 1. Create Test Runner Repository
4+
5+
1. Create a new repository named `scan-test-runner-azure-devops` in your Azure DevOps project
6+
2. Add the pipeline configuration at `azure-pipelines.yml`
7+
3. Create a pipeline from the YAML file
8+
9+
---
10+
11+
## 2. Register Microsoft Entra ID Application
12+
13+
1. Navigate to Azure Portal:
14+
**Microsoft Entra ID → App registrations → New registration**
15+
16+
Direct link: https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps/CreateApplicationBlade
17+
18+
2. Configure the application:
19+
20+
| Field | Value |
21+
|-----------------------------|------------------------------------------------|
22+
| **Name** | `BoostSecurity.io Scan Test Runner` |
23+
| **Supported account types** | Accounts in this organizational directory only |
24+
| **Redirect URI** | Leave blank |
25+
26+
3. Click **Register**
27+
28+
4. Note the **Application (client) ID** and **Directory (tenant) ID** from the overview page
29+
30+
---
31+
32+
## 3. Add Federated Credential for GitHub Actions
33+
34+
1. In the app registration, go to:
35+
**Certificates & secrets → Federated credentials → Add credential**
36+
37+
2. Select **GitHub Actions deploying Azure resources**
38+
39+
3. Configure the federated credential:
40+
Need to be done for both
41+
- boostsecurityio/dev-registry
42+
- boost-community/scanner-registry
43+
44+
| Field | Value |
45+
|------------------------|---------------------|
46+
| **Organization** | <org name> |
47+
| **Repository** | <repo name> |
48+
| **Entity type** | Pull Request |
49+
| **Name** | `github-actions-pr` |
50+
51+
4. Click **Add**
52+
53+
---
54+
55+
## 4. Grant Permissions in Azure DevOps
56+
57+
1. Navigate to your Azure DevOps organization:
58+
**Organization Settings → Users → Add users**
59+
60+
Or: `https://dev.azure.com/{ORG}/_settings/users`
61+
62+
2. Add the service principal:
63+
- Search for the app name: `BoostSecurity.io Scan Test Runner`
64+
- Access level: **Basic**
65+
- Add to project: Select your project
66+
67+
3. Navigate to project permissions:
68+
**Project Settings → Permissions → {Your Project} Team → Members → Add**
69+
70+
4. Add the service principal with **Build Administrator** role (or create a custom role with Build: Read & Execute)
71+
72+
---
73+
74+
## 5. Configure Secrets on Scanner Registry Repository
75+
76+
Navigate to the scanner registry repository (GitHub):
77+
**Settings → Secrets and variables → Actions → New repository secret**
78+
79+
| Secret Name | Value |
80+
|-----------------------------------|-------------------------------------|
81+
| `BOOST_SCAN_RUNNER_ADO_TENANT_ID` | Directory (tenant) ID from step 2 |
82+
| `BOOST_SCAN_RUNNER_ADO_CLIENT_ID` | Application (client) ID from step 2 |
83+
84+
85+
---
86+
87+
## 6. Usage in GitHub Actions Workflow
88+
89+
```yaml
90+
permissions:
91+
id-token: write # Required for OIDC
92+
contents: read
93+
94+
jobs:
95+
test:
96+
runs-on: ubuntu-latest
97+
steps:
98+
- name: Azure Login (OIDC)
99+
uses: azure/login@v2
100+
with:
101+
client-id: ${{ secrets.AZURE_CLIENT_ID }}
102+
tenant-id: ${{ secrets.AZURE_TENANT_ID }}
103+
allow-no-subscriptions: true
104+
105+
- name: Get Azure DevOps Token
106+
id: azure-token
107+
run: |
108+
token=$(az account get-access-token \
109+
--resource 499b84ac-1321-427f-aa17-267ca6975798 \
110+
--query accessToken -o tsv)
111+
echo "token=$token" >> $GITHUB_OUTPUT
112+
echo "::add-mask::$token"
113+
114+
- name: Run test-action
115+
...
116+
```
117+
118+
---
119+
120+
## 7. Token Details
121+
122+
| Property | Value |
123+
|----------------------|--------------------------------------|
124+
| **Lifetime** | ~1 hour |
125+
| **Refresh** | New token generated per workflow run |
126+
| **Secrets Required** | None (OIDC federation) |
127+
128+
---
129+
130+
## References
131+
132+
- [Configure OIDC for GitHub Actions and Azure](https://docs.github.com/en/actions/security-for-github-actions/security-hardening-your-deployments/configuring-openid-connect-in-azure)
133+
- [Workload Identity Federation](https://learn.microsoft.com/en-us/entra/workload-id/workload-identity-federation)
134+
- [Azure DevOps REST API Authentication](https://learn.microsoft.com/en-us/azure/devops/integrate/get-started/authentication/service-principal-managed-identity)
135+
- [azure/login GitHub Action](https://github.com/Azure/login)

‎docs/setup-bitbucket.md‎

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
# Bitbucket Test Runner Setup
2+
3+
## 1. Create Test Runner Repository
4+
5+
1. Create a new repository named `scan-test-runner-bitbucket-pipelines` in your Bitbucket workspace
6+
2. Add the pipeline configuration at `bitbucket-pipelines.yml`
7+
3. Enable Pipelines: **Repository settings → Pipelines → Settings → Enable Pipelines**
8+
9+
---
10+
11+
## 2. Create OAuth2 Consumer
12+
13+
1. Navigate to your workspace settings:
14+
**Workspace → Settings → OAuth consumers → Add consumer**
15+
16+
Direct link: `https://bitbucket.org/{WORKSPACE}/workspace/settings/api`
17+
18+
2. Configure the OAuth consumer:
19+
20+
| Field | Value |
21+
|--------------------------------|------------------------------------------------------|
22+
| **Name** | `BoostSecurity.io Scan Test Runner` |
23+
| **Callback URL** | `http://localhost` (not used for client credentials) |
24+
| **This is a private consumer** | ✅ Checked |
25+
26+
3. Set **Permissions**:
27+
28+
| Permission | Access |
29+
|------------------|--------|
30+
| **Repositories** | Read |
31+
| **Pipelines** | Read |
32+
| **Pipelines** | Write |
33+
34+
4. Click **Save**
35+
36+
5. Note the **Key** (client ID) and **Secret** - the secret is only shown once!
37+
38+
---
39+
40+
## 3. Configure Secrets on Scanner Registry Repository
41+
42+
Navigate to the scanner registry repository (GitHub):
43+
**Settings → Secrets and variables → Actions → New repository secret**
44+
45+
| Secret Name | Value |
46+
|---------------------------------------------|--------------------|
47+
| `BOOST_SCAN_RUNNER_BITBUCKET_CLIENT_ID` | Key from step 2 |
48+
| `BOOST_SCAN_RUNNER_BITBUCKET_CLIENT_SECRET` | Secret from step 2 |
49+
50+
51+
---
52+
53+
## 4. Usage in GitHub Actions Workflow
54+
55+
```yaml
56+
- name: Generate Bitbucket OAuth Token
57+
id: bitbucket-token
58+
run: |
59+
response=$(curl -s -X POST \
60+
"https://bitbucket.org/site/oauth2/access_token" \
61+
-u "${{ secrets.BITBUCKET_CLIENT_ID }}:${{ secrets.BITBUCKET_CLIENT_SECRET }}" \
62+
-d "grant_type=client_credentials")
63+
64+
token=$(echo "$response" | jq -r '.access_token')
65+
echo "token=$token" >> $GITHUB_OUTPUT
66+
echo "::add-mask::$token"
67+
68+
- name: Run test-action
69+
...
70+
```
71+
72+
---
73+
74+
## 5. Token Details
75+
76+
| Property | Value |
77+
|--------------|--------------------------------------------|
78+
| **Lifetime** | 2 hours |
79+
| **Refresh** | New token generated per workflow run |
80+
| **Scopes** | `repository`, `pipeline`, `pipeline:write` |
81+
82+
---
83+
84+
## 6. API Endpoints
85+
86+
| Operation | Endpoint |
87+
|-------------------------|--------------------------------------------------------------------------------------|
88+
| **Trigger Pipeline** | `POST https://api.bitbucket.org/2.0/repositories/{workspace}/{repo}/pipelines/` |
89+
| **Get Pipeline Status** | `GET https://api.bitbucket.org/2.0/repositories/{workspace}/{repo}/pipelines/{uuid}` |
90+
91+
---
92+
93+
## References
94+
95+
- [Bitbucket OAuth2](https://support.atlassian.com/bitbucket-cloud/docs/use-oauth-on-bitbucket-cloud/)
96+
- [OAuth2 Client Credentials Grant](https://support.atlassian.com/bitbucket-cloud/docs/use-oauth-on-bitbucket-cloud/#Client-credentials-Grant--4-LO-)
97+
- [Bitbucket Pipelines API](https://developer.atlassian.com/cloud/bitbucket/rest/api-group-pipelines/)

0 commit comments

Comments
 (0)