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

# ┌─────────── 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

apiVersion: v1kind: Secretmetadata:  name: github-token  namespace: ssd-systemtype: OpaquestringData:  username: "<github-username>"  password: "<personal-access-token>"

Required permissions: repo (read access to code)

Docker Registry Credentials

bash

kubectl create secret docker-registry docker-registry \  --namespace ssd-system \  --docker-server=<registry-url> \  --docker-username=<username> \  --docker-password=<password>

AWS ECR Credentials

bash

aws ecr get-login-password --region <region> | \  kubectl create secret docker-registry ecr-registry \    --namespace ssd-system \    --docker-server=<account>.dkr.ecr.<region>.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

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

# List all on-demand scan configskubectl get scanconfigs -n ssd-system# View a specific scan configkubectl describe scanconfig <name> -n ssd-system# List all scan jobskubectl get scanjobs -n ssd-system# View a specific scan job statuskubectl describe scanjob <job-name> -n ssd-system

---

Troubleshooting

Check Agent Logs

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

kubectl get crds | grep ssd.opsmx.io# Expected:# scanconfigs.ssd.opsmx.io# scanjobs.ssd.opsmx.io

Test RBAC Permissions

bash

kubectl auth can-i create scanjobs.ssd.opsmx.io \  --as system:serviceaccount:ssd-system:ssd-shield-agent# Expected: yes

Verify Gateway Connectivity

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