ansible-testing/instructions.md

# 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.