CYBER-0 changes to secret management from stored config to individual variables
This commit is contained in:
Ole Valente
+137
@@ -0,0 +1,137 @@
|
||||
# Test Execution Instructions
|
||||
|
||||
This guide walks a tester through configuring a test environment, defining its
|
||||
secrets, and running the compliance pipeline in GitLab CI. Secrets are supplied
|
||||
as individual GitLab CI/CD variables; no secrets file is committed to the
|
||||
repository.
|
||||
|
||||
---
|
||||
|
||||
## 1. Define the project and targets in `assets.yml`
|
||||
|
||||
`assets.yml` is the single source of non-secret project and target data. It is
|
||||
both an Ansible inventory and the input GitLab CI validates.
|
||||
|
||||
### Project metadata
|
||||
|
||||
Under `all.vars.test_project`, set:
|
||||
|
||||
```yaml
|
||||
all:
|
||||
vars:
|
||||
test_project:
|
||||
id: "baggage-handling" # unique project identifier
|
||||
name: "Baggage Handling HLC" # display name for reports
|
||||
environment: "test" # must match TARGET_ENVIRONMENT
|
||||
customer: "Customer X"
|
||||
location: "testserv"
|
||||
```
|
||||
|
||||
> The `environment` value is the GitLab environment scope that selects the
|
||||
> matching secrets. `test`, `acceptance`, and `production` are typical values.
|
||||
|
||||
### Targets
|
||||
|
||||
Add each host under the matching group in `all.children`, for example:
|
||||
|
||||
```yaml
|
||||
linux_vms:
|
||||
hosts:
|
||||
linux-app-01:
|
||||
ansible_host: 192.0.2.10
|
||||
asset_type: linux_vm
|
||||
test_profiles: [iec62443, sbom]
|
||||
```
|
||||
|
||||
Supported groups and their required connection settings are already defined in
|
||||
`assets.yml`:
|
||||
|
||||
| Group | Connection | Example secret variables needed |
|
||||
| --- | --- | --- |
|
||||
| `linux_vms` | SSH | `ANSIBLE_USER`, `ANSIBLE_PASSWORD`, `ANSIBLE_BECOME_PASSWORD` |
|
||||
| `windows_servers` / `windows_clients` / `mssql_servers` / `hyperv_hosts` | WinRM | `ANSIBLE_USER`, `ANSIBLE_PASSWORD` |
|
||||
| `vmware_esxi` | vCenter API | `VCENTER_HOSTNAME`, `VCENTER_USERNAME`, `VCENTER_PASSWORD` |
|
||||
| `cisco_switches` / `cisco_firewalls` | network_cli | `ANSIBLE_USER`, `ANSIBLE_PASSWORD`, `ANSIBLE_BECOME_PASSWORD` |
|
||||
|
||||
Keep credentials out of this file.
|
||||
|
||||
---
|
||||
|
||||
## 2. Define secrets as GitLab CI/CD variables
|
||||
|
||||
Open the project in GitLab: **Settings → CI/CD → Variables → Add variable**.
|
||||
|
||||
Add one variable per secret. Set the **Environment scope** to the exact value of
|
||||
`all.vars.test_project.environment` (for example `test`), so secrets are only
|
||||
injected into tool jobs that declare that environment.
|
||||
|
||||
| Key | Type | Protected | Masking | Notes |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| `ANSIBLE_USER` | Variable | recommended | Masked | Login account, e.g. `DOMAIN\automation-user` |
|
||||
| `ANSIBLE_PASSWORD` | Variable | yes | Masked and hidden | Login password |
|
||||
| `ANSIBLE_BECOME_PASSWORD` | Variable | yes | Masked and hidden | Sudo/enable password (Linux, Cisco) |
|
||||
| `VCENTER_HOSTNAME` | Variable | recommended | Masked | vCenter appliance, e.g. `vcenter.example.com` |
|
||||
| `VCENTER_USERNAME` | Variable | recommended | Masked | e.g. `automation@vsphere.local` |
|
||||
| `VCENTER_PASSWORD` | Variable | yes | Masked and hidden | vCenter password |
|
||||
| `ANSIBLE_PRIVATE_KEY` | File | yes | — | Optional: SSH private key for key auth |
|
||||
|
||||
Rules:
|
||||
|
||||
- Define **only the variables required by the targets in `assets.yml`**.
|
||||
- Use **Masked and hidden** (GitLab 15.10+) for values containing spaces or
|
||||
special characters; standard **Masked** rejects those formats.
|
||||
- Do not enable `CI_DEBUG_TRACE` on pipelines that receive secrets.
|
||||
|
||||
The `test:ansible` job runs `methodologies/ansible/scripts/build-secrets.py`,
|
||||
which assembles these variables into a temporary vars file and passes it to
|
||||
Ansible via `--extra-vars @<file>`. Values never appear in the job log or on the
|
||||
process command line.
|
||||
|
||||
---
|
||||
|
||||
## 3. Run the pipeline
|
||||
|
||||
1. Push your `assets.yml` changes (and any repository changes) to the branch you
|
||||
want to test.
|
||||
2. In GitLab, open **CI/CD → Pipelines → Run pipeline** (or **New pipeline**).
|
||||
3. Set the pipeline variables:
|
||||
|
||||
| Variable | Value | Purpose |
|
||||
| --- | --- | --- |
|
||||
| `TARGET_ENVIRONMENT` | `test` (or your environment) | Selects the environment scope; must match `assets.yml` |
|
||||
| `RUN_ANSIBLE` | `true` | Enables the infrastructure tests |
|
||||
| `RUN_ZAP` | `true` | Enables web tests (only once the ZAP methodology is enabled) |
|
||||
| `ANSIBLE_LIMIT` | e.g. `linux_vms` or `linux-app-01` | Optional: restrict the run to a host or group (defaults to `all`) |
|
||||
|
||||
4. Start the pipeline.
|
||||
|
||||
The pipeline validates that `TARGET_ENVIRONMENT` matches `assets.yml` before any
|
||||
testing begins. A mismatch stops the run in the `validate` stage.
|
||||
|
||||
---
|
||||
|
||||
## 4. Check the results
|
||||
|
||||
Pipeline stages: `validate → build → platform → test → normalize → report`.
|
||||
|
||||
- `test:ansible` runs the compliance checks against the selected assets.
|
||||
- `normalize` converts the tool output into the common schema.
|
||||
- `report` produces Markdown, HTML, and PDF.
|
||||
|
||||
Download artifacts from the pipeline page (**Download artifacts** on the job, or
|
||||
the pipeline's **Artifacts** menu):
|
||||
|
||||
```text
|
||||
artifacts/
|
||||
├── raw/ansible/ native Ansible output
|
||||
├── normalized/ common JSON schema
|
||||
└── rendered/ Markdown, HTML, and PDF reports
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Rotating a secret
|
||||
|
||||
Replace the value of the GitLab CI/CD variable under the matching environment
|
||||
scope. No repository change is required. Existing artifacts contain only
|
||||
normalized findings, never the secret values.
|
||||
Reference in New Issue
Block a user