# Security Scan Agent

### What it does

The Security Scan Agent runs comprehensive security audits on your codebase—scanning for secrets, vulnerable dependencies, code vulnerabilities, and container issues—all in one command.

Think of it as your automated security engineer that checks everything before you commit.

**You'll get:**

* Exposed API keys and credentials detected
* Vulnerable dependencies with exact fix commands
* OWASP Top 10 vulnerabilities flagged
* Container and infrastructure security issues
* Actionable remediation steps

⏱️ **Scan time:** 2-5 minutes depending on project size

## Sample Prompts

{% hint style="success" %}
**Examples**

#### **pre‑merge‑secret‑sweep**

**Prompt:** "Scan only for exposed secrets in the feature branch before merging.”

#### **release‑v1.0‑vuln‑audit** 

**Prompt**: “Perform a high‑severity vulnerability audit of the codebase ahead of v1.0 release.”

#### **nightly‑iac‑check**

**Prompt:** “Run an infrastructure‑as‑code compliance check on `infra/` every night.”

#### **ci‑sast‑python**

**Prompt:** “Static analysis of all Python files with medium severity in the CI pipeline.”

#### **monthly‑full‑security**

**Prompt:** “Execute a comprehensive full‑repo security scan as part of monthly governance.”
{% endhint %}

### Why use it

**Instead of:**

* Running 4 separate security tools manually
* Spending hours reviewing scan results
* Googling how to fix vulnerabilities

**You get:**

* One command that runs everything
* Exact fix commands (e.g., `npm install package@version`)
* Auto-installation of missing security tools
* Clear risk scores and prioritized fixes

**Impact:**

* 70-85% reduction in exploitable vulnerabilities
* 12-20 hours saved per week per team
* Catch issues before they reach production

### What it scans

The agent performs 4 types of security scans:

#### 1. Secrets Detection

**Tool:** Gitleaks\
**Finds:** Hardcoded API keys, tokens, passwords, credentials\
**Example:** AWS keys, GitHub tokens, database passwords in config files

#### 2. Dependency Scanning

**Tool:** Built-in audits (npm, pip, etc.)\
**Finds:** Known CVEs in third-party packages\
**Example:** Vulnerable versions of Express, Django, React

#### 3. Source Code Analysis (SAST)

**Tool:** Semgrep\
**Finds:** OWASP Top 10 vulnerabilities in your code\
**Example:** SQL injection, XSS, insecure authentication

#### 4. Container & Infrastructure

**Tool:** Trivy, policy validators\
**Finds:** Container vulnerabilities, IaC misconfigurations\
**Example:** Outdated base images, insecure Terraform configs

***

### How to use it

#### Basic scan

Run a full security audit on your current directory:

bash

```bash
/opsera-devops-agent:security-scan
```

or in natural language:

```
"Run a security scan on this project"
```

***

#### Specific scans

**Secrets only:**

```
"Run a secrets-only scan"
```

**High severity only:**

```
"Run a full scan but only show critical and high severity issues"
```

**Specific directory:**

```
"Scan the ./src directory for security vulnerabilities"
```

***

### What you'll see

#### During the scan

```bash
🔍 Security Scan Agent Starting...

Phase 1/6: Pre-flight checks...
✓ Project validated
✓ Security tools detected

Phase 2/6: Secrets detection...
✗ Found 2 exposed credentials
  - AWS_ACCESS_KEY in config.js:12
  - GITHUB_TOKEN in .env:5

Phase 3/6: Dependency scanning...
! Found 3 vulnerable packages
  - express@4.17.1 (CVE-2024-1234)
  - lodash@4.17.19 (CVE-2024-5678)

Phase 4/6: SAST analysis...
✗ Found 1 SQL injection vulnerability
  - src/api/users.js:42

Phase 5/6: Container scanning...
✓ No container vulnerabilities found

Phase 6/6: Generating report...
✓ Report saved: security-scan-report.html
```

***

#### Report summary

```
Security Scan Results
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Risk Score: 68/100 (High Risk)

Findings by Severity:
  🔴 Critical: 2
  🟠 High: 3
  🟡 Medium: 5
  🟢 Low: 8

Scan Coverage: 100%
  ✓ Secrets Detection
  ✓ Dependency Scanning
  ✓ SAST Analysis
  ✓ Container Scanning

Top Priority Fixes:
1. Revoke exposed AWS credentials (config.js:12)
2. Update express to 4.18.2: npm install express@4.18.2
3. Fix SQL injection in src/api/users.js:42
```

***

### Quality gates

Use these benchmarks to measure your security posture:

| Metric                | Target     | Purpose                                   |
| --------------------- | ---------- | ----------------------------------------- |
| **Critical Findings** | 0          | Block deployment if critical issues exist |
| **Risk Score**        | < 20/100   | Maintain low overall risk                 |
| **Scan Coverage**     | 100%       | All 4 scan types completed                |
| **Time to Fix**       | < 24 hours | Critical issues resolved quickly          |

**Recommended thresholds:**

* **Pass:** 0 critical, risk score < 20
* **Warning:** 0 critical, risk score 20-50
* **Fail:** Any critical findings or risk score > 50

***

### After the scan

#### 1. Fix critical issues immediately

**Exposed secrets:**

```bash
# Revoke the token immediately
# Rotate credentials in your cloud provider
# Remove from code and add to .gitignore
```

**Critical vulnerabilities:**

```bash
# Use the exact commands from the report:
npm install express@4.18.2
npm install lodash@4.17.21
```

***

#### 2. Review the detailed report

Open the generated report:

```bash
security-scan-report.html
```

This includes:

* Line-by-line code references
* CVE details and severity scores
* Step-by-step remediation instructions
* Before/after code examples

***

#### 3. Install missing tools (if needed)

If the scan shows incomplete coverage:

```bash
# macOS
brew install gitleaks semgrep trivy

# Linux
# Follow instructions in the scan output
```

***

#### 4. Re-scan to verify

After fixing issues, run the scan again:

```bash
/opsera-devops-agent:security-scan
```

Your risk score should improve and findings should decrease.

***

### Common issues

**"Tool not found" errors?**

* Install missing tools: `brew install gitleaks semgrep`
* Or let the agent try to install them automatically

**Scan taking too long?**

* Run specific scans: "Run a secrets-only scan"
* Exclude directories: "Scan but skip node\_modules"

**Too many false positives?**

* Focus on critical/high: "Show only critical and high severity"
* Configure suppressions in the report

**Report not generating?**

* Check disk space
* Verify write permissions in current directory
* Look for errors in scan output

### Examples

**Quick security check before commit:**

```
"Run a quick security scan and show me any critical issues"
```

**Full audit for production release:**

```
"Run a comprehensive security scan with all checks enabled"
```

**Focus on dependencies:**

```
"Scan my dependencies for known CVEs and show me how to fix them"
```

**Check for exposed secrets:**

```
"Scan for exposed API keys and credentials in this repository"
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.agents.opsera.ai/devsecops-agents/security-scan-agent.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.