138 lines
5.1 KiB
Markdown
138 lines
5.1 KiB
Markdown
# 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.
|