> For the complete documentation index, see [llms.txt](https://docs.opsmx.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.opsmx.com/remediation-agents/kubernetes-agent-delegate/on-demand-scanning.md). # On-Demand Scanning On-Demand Scanning is the capability that allows security teams to configure and trigger vulnerability scans **directly from the Delivery Shield dashboard** — without needing to configure webhooks, push events, or wait for pipeline triggers. **How On-Demand Scanning Works** 1. **Create a Scan Config** — Define what to scan (repository or registry), which scanners to use, and an optional schedule 2. **Config Sent to Agent** — The gateway sends the configuration to the selected agent via gRPC; the agent stores it as a `ScanConfig` CRD in the Kubernetes cluster 3. **Trigger a Scan** — Click **Run** for an immediate scan, or let the cron schedule handle automatic execution 4. **View Results** — Scan results appear on the **Reports page** once the agent completes the scan and reports back to the gateway **Creating a Scan Config** Navigate to **Scan Configs** → click **New Scan Config** and provide: **Supported Scanners** *** ### Triggering Scans Once a Scan Config is created, scans can be triggered in three ways: *** ### Scheduled Scans Scheduled scans run **on the agent side** — independently of the gateway. This means scheduled scans continue to execute even if the gateway is temporarily unavailable. **Schedule Options** **Cron Expression Format** bash ```bash # ┌─────────── minute (0–59)# │ ┌─────────── hour (0–23)# │ │ ┌─────────── day of month (1–31)# │ │ │ ┌─────────── month (1–12)# │ │ │ │ ┌─────────── day of week (0–6, Sun=0)# │ │ │ │ │ * * * * *# Common examples:0 6 * * 1-5 # Weekdays at 6:00 AM0 0 1 * * # First day of every month*/15 * * * * # Every 15 minutes0 9,17 * * * # At 9:00 AM and 5:00 PM ``` **How Scheduling Works** * Schedules are managed by the agent using the internal cron library and persist as `ScanConfig` CRDs * On agent restart, all schedules are **automatically reloaded** from existing CRDs — no reconfiguration needed * If the agent is down during a scheduled time, that execution is **skipped** and resumes on the next scheduled tick * Scheduled scans create `ScanJob` CRDs just like webhook-triggered or manually triggered scans **Scheduling Best Practices** * **Stagger schedules** — avoid scheduling all scans at the same time to prevent resource spikes on the cluster * **Use daily scans for baseline** — a daily midnight scan provides a consistent, comparable security baseline over time * **Combine with polling** — use scheduled scans for full periodic checks and polling for change-driven scans * **Set appropriate timeouts** — large repositories may need longer timeout values (default: 1800 seconds) *** ### Polling Watchers For repositories and registries where webhooks cannot be configured, **Polling Watchers** periodically check for changes and automatically trigger scans when new commits, tags, or images are detected. **When to Use Polling** * **No webhook access** — cannot configure webhooks on the repository (e.g., third-party or read-only repos) * **Firewall restrictions** — the agent cluster is not reachable from the internet for webhook delivery * **Registry monitoring** — watching for new container image tags pushed to a registry * **Supplement webhooks** — use polling as a safety net alongside webhooks to catch missed events **Enabling Polling** In the scan config form, check **Enable Outbound Polling** in the Schedule & Polling section: **What Polling Detects** * **New commits** — detects when the HEAD of a monitored branch changes * **New tags** — detects new Git tags (e.g., release tags) * **New images** — detects new image tags or digest changes in container registries **Note:** The first poll establishes a baseline — no scans are triggered until subsequent polls detect changes. **Recommended Polling Intervals** Shorter intervals increase API rate limit consumption. Ensure your token has sufficient rate limits for the number of monitored repositories. *** ### Polling vs Webhooks vs Scheduled Scans *** ### Repository & Registry Discovery The **Discovery** feature lets teams browse organizations, repositories, and branches directly from the Delivery Shield dashboard — without manually entering URLs. **How Discovery Works** 1. The gateway sends a discovery request to the selected agent via gRPC 2. The agent reads the specified Kubernetes Secret to obtain the access token 3. The agent calls the provider API (GitHub, GitLab, or Docker Registry) to list available resources 4. Results are sent back to the gateway and displayed as dropdown options in the Scan Config UI **Security:** Credentials stay entirely within your Kubernetes cluster. The gateway never sees or stores tokens — it only receives the list of discovered resource names. *** ### Credentials Setup All credentials for accessing private repositories and registries are stored as Kubernetes Secrets in the agent's cluster namespace — never transmitted to the gateway. **GitHub / GitLab Token** yaml ```yaml apiVersion: v1kind: Secretmetadata: name: github-token namespace: ssd-systemtype: OpaquestringData: username: "" password: "" ``` **Required permissions:** `repo` (read access to code) **Docker Registry Credentials** bash ```bash kubectl create secret docker-registry docker-registry \ --namespace ssd-system \ --docker-server= \ --docker-username= \ --docker-password= ``` **AWS ECR Credentials** bash ```bash aws ecr get-login-password --region | \ kubectl create secret docker-registry ecr-registry \ --namespace ssd-system \ --docker-server=.dkr.ecr..amazonaws.com \ --docker-username=AWS \ --docker-password-stdin ``` **Note:** ECR tokens expire after 12 hours. Use a CronJob or External Secrets Operator for automatic token rotation. **Referencing Credentials in ScanConfig** yaml ```yaml apiVersion: ssd.opsmx.io/v1kind: ScanConfigmetadata: name: default namespace: ssd-systemspec: credentials: git: name: github-token namespace: ssd-system registry: name: docker-registry namespace: ssd-system scanners: - name: Container Security Scan enabled: true ``` *** ### Managing Scan Configs via kubectl Since scan configs are stored as Kubernetes CRDs, they can be managed directly via `kubectl` alongside the dashboard: bash ```bash # List all on-demand scan configskubectl get scanconfigs -n ssd-system# View a specific scan configkubectl describe scanconfig -n ssd-system# List all scan jobskubectl get scanjobs -n ssd-system# View a specific scan job statuskubectl describe scanjob -n ssd-system ``` *** ### Troubleshooting **Check Agent Logs** bash ```bash # Controller logs — gateway communication and job managementkubectl logs -n ssd-system -l app.kubernetes.io/component=controller -f# Collector logs — webhook handling and event processingkubectl logs -n ssd-system -l app.kubernetes.io/component=collector -f# Check for errors in the last hourkubectl logs -n ssd-system -l app.kubernetes.io/name=ssd-shield-agent \ --since=1h | grep -i error ``` **Verify CRDs Are Installed** bash ```bash kubectl get crds | grep ssd.opsmx.io# Expected:# scanconfigs.ssd.opsmx.io# scanjobs.ssd.opsmx.io ``` **Test RBAC Permissions** bash ```bash kubectl auth can-i create scanjobs.ssd.opsmx.io \ --as system:serviceaccount:ssd-system:ssd-shield-agent# Expected: yes ``` **Verify Gateway Connectivity** bash ```bash # Check configured gateway endpointkubectl get configmap ssd-agent-config -n ssd-system -o yaml | grep endpoint# Test mTLS certificate validitykubectl exec -n ssd-system deploy/ssd-shield-agent -- \ openssl x509 -in /etc/ssd-agent/certs/tls.crt -noout -dates ``` **Common Issues & Resolutions**