CYBER-0 initial concept ready

docs/architecture.md

@@ -0,0 +1,96 @@
+# Test Automation Architecture
+
+## Responsibilities
+
+GitLab CI is the orchestrator. It validates the project configuration, starts
+tool-specific Kubernetes jobs, collects raw output, invokes normalizers, and
+publishes rendered reports. Ansible is one test executor alongside ZAP and
+future tools; it is not the pipeline controller.
+
+```mermaid
+flowchart LR
+    A[assets.yml] --> V[Validate and prepare]
+    V --> K[k3s tool jobs]
+    K --> AN[Ansible]
+    K --> Z[ZAP]
+    K --> O[Other tools]
+    AN --> R[Raw artifacts]
+    Z --> R
+    O --> R
+    R --> N[Tool adapters]
+    N --> J[Normalized JSON]
+    J --> D[Markdown / HTML / PDF]
+    D --> G[GitLab artifacts]
+```
+
+## Data Contracts
+
+- `assets.yml` is the canonical project and asset list. It is valid Ansible
+  YAML inventory and is parsed during pipeline preparation for CI metadata.
+- Tool output is retained unchanged under `artifacts/raw/<tool>/`.
+- Every adapter writes schema-valid reports under `artifacts/normalized/`.
+- `schemas/test-report.schema.json` is the versioned interface between tools
+  and report generation. Standards mappings belong on individual results, so
+  IEC 62443 and OWASP ASVS findings can coexist without flattening semantics.
+- Generated Markdown, HTML, and PDF files are stored under
+  `artifacts/rendered/` and uploaded as GitLab artifacts.
+- `TARGET_ENVIRONMENT` selects GitLab environment-scoped variables and must
+  match the environment declared in `assets.yml`. Only tool jobs declare that
+  GitLab environment, keeping secrets out of validation and rendering jobs.
+
+## Kubernetes State
+
+The `test-automation` namespace contains reusable platform state. The initial
+manifests request one volume using the cluster's default StorageClass:
+
+`tool-cache` is a long-lived, replaceable cache for downloaded vulnerability
+databases, scanner rules, and package indexes.
+
+Pipeline evidence is never authoritative on a PVC. GitLab artifacts are the
+immutable record and receive an explicit retention policy. Databases that
+require transactions or concurrent writers should use a dedicated StatefulSet
+and PVC rather than the shared cache. Back up only state that cannot be
+reconstructed from an upstream feed.
+
+ZAP jobs are ephemeral and receive no persistent ZAP home by default. This
+prevents sessions, authentication state, and target data from leaking between
+projects. Only a future explicitly reviewed ZAP add-on cache should use
+`tool-cache`.
+
+## Job Isolation
+
+Each GitLab CI job is already an ephemeral pod because `testserv` uses the
+Kubernetes executor. Tool jobs receive the checked-out project, narrowly scoped
+credentials, resource requests and limits, and the shared tool cache. Output is
+written to the GitLab workspace and uploaded directly as pipeline artifacts.
+NetworkPolicy should be added once target ranges and proxy requirements are known.
+
+## Required Runner Configuration
+
+The runner manager on `testserv` uses the `ci/gitlab-runner` ServiceAccount.
+Configure its Helm values so `[runners.kubernetes].namespace` is
+`test-automation`, and mount the `tool-cache` PVC at `/cache/tools`. The
+cross-namespace RoleBinding in `platform/kubernetes/runner-rbac.yml` grants only
+the pod, attach, log, Secret, Service, and event operations required by GitLab's
+Kubernetes executor.
+
+Bootstrap the namespace, storage, and RBAC once with an administrator context:
+
+```bash
+kubectl apply -k platform/kubernetes
+```
+
+CI tool pods do not need Kubernetes API credentials. The runner manager uses its
+in-cluster identity to create and clean them up. Do not copy the admin kubeconfig
+into GitLab CI.
+
+## Delivery Sequence
+
+1. Make inventory validation, schema validation, and report rendering mandatory.
+2. Run Ansible in its GitLab Kubernetes-executor pod and normalize its JSON.
+3. Add ZAP Automation Framework plans and a ZAP-to-common-schema adapter with
+   ASVS mappings.
+4. Add SBOM generation through Ansible for Windows and Linux targets; preserve
+   CycloneDX as a raw artifact and normalize policy findings separately.
+5. Add aggregate project reports and quality-gate policies after result semantics
+   are stable.

docs/secrets.md

@@ -0,0 +1,70 @@
+# Environment-Specific Secrets
+
+GitLab CI/CD variables are the secret source of record. `assets.yml` contains
+only non-secret project, host, and test-profile data.
+
+## Environment Selection
+
+Start a pipeline with `TARGET_ENVIRONMENT` set to the intended GitLab
+environment scope, for example `test`, `acceptance`, or `production`. The value
+must exactly match `all.vars.test_project.environment` in `assets.yml`.
+
+Tool jobs declare:
+
+```yaml
+environment:
+  name: "$TARGET_ENVIRONMENT"
+  action: verify
+```
+
+GitLab therefore injects variables matching that environment scope only into
+tool jobs. Validation and report jobs do not declare an environment and should
+not receive these credentials.
+
+Configure each secret under **Settings > CI/CD > Variables** with:
+
+- an exact environment scope such as `test` or `production`;
+- **Protected** enabled for protected environments;
+- **Masked** or **Masked and hidden** where the value format permits it;
+- **File** type for keys, certificates, and structured variable files.
+
+Do not enable `CI_DEBUG_TRACE` in pipelines that receive secrets.
+
+## Ansible Variables
+
+Create `ANSIBLE_SECRET_VARS` as an environment-scoped **File** variable. Its
+contents are an Ansible YAML or JSON variables file, for example:
+
+```yaml
+ansible_user: "DOMAIN\\automation-user"
+ansible_password: "replace-in-gitlab"
+ansible_become_password: "replace-in-gitlab"
+vcenter_username: "automation@vsphere.local"
+vcenter_password: "replace-in-gitlab"
+```
+
+The `test:ansible` job checks that the variable resolves to a file and exports
+its temporary path as `ANSIBLE_VARS_FILE`. The methodology runner passes it with
+`--extra-vars @<file>` without printing the contents or putting values in the
+process command line.
+
+For SSH key authentication, add `ANSIBLE_PRIVATE_KEY_FILE` as a separate
+environment-scoped **File** variable. The methodology runner passes that path through
+`--private-key` when present.
+
+The current job assumes one credential set per test environment. Environments
+with distinct Windows, Linux, network, or hypervisor credentials should be split
+into separate tool jobs, each referencing its own scoped File variable.
+
+## ZAP Variables
+
+ZAP authentication will use individually masked variables referenced by its
+Automation Framework plan, such as `ZAP_USERNAME`, `ZAP_PASSWORD`, or
+`ZAP_AUTH_HEADER_VALUE`. Define only those required by the selected application.
+The ZAP adapter and authentication plan are intentionally not enabled yet.
+
+## Rotation
+
+Rotate a secret by replacing the value in each GitLab environment scope. No
+repository change is required. Existing artifacts contain normalized findings,
+not the GitLab variable files, and the pipeline never uploads secret paths.