# githubVulnerabilityScan

Runs the [GitHub vulnerability scanner](https://github.com/theorchard/security-scripts/tree/master/github_vuln_scanner) against the PR which triggered the pipeline.

This step will fail if called from a pipeline which was not triggered by a PR.

## Parameters

| Name         | Description | Type | Default | Required |
|--------------|-------------|------|---------|----------|
| projectDir   | The subdirectory to run the scan against. This must be a relative path to the repository root. | `string` | n/a | no |
| scannerImage | The URI of the Docker image to use to perform the scan. This must be an ECR image. | `string` | `086679231553.dkr.ecr.us-east-1.amazonaws.com/security-scripts/github-vuln-scanner:latest` | no |
| repoOwner    | The GitHub repository owner. Auto-detected from `GIT_URL` if not set. | `string` | Extracted from `GIT_URL` | no |
| excludedPath | Comma-separated paths to exclude from scanning. `sonar-scanner-temp` and `dockerToEcr` are always excluded by default. | `string` | `sonar-scanner-temp,dockerToEcr` | no |
| skipPhrase   | Phrase in PR comment that skips the scan. | `string` | `skip vulnerability scan` | no |
| ux           | Output format for PR comments. Allowed values: `table` or `markdown`. `rich` is not allowed with `--post-comment`. | `string` | scanner default | no |
| logLevel     | Logging level: `debug`, `info`, `warning`, `error`, `critical`. | `string` | `info` | no |

> Note: `sonar-scanner-temp` and `dockerToEcr` are automatically excluded to prevent false positives from SonarQube and DockerToECR temporary clones/workspaces.

## Default Scanner Image

`086679231553.dkr.ecr.us-east-1.amazonaws.com/security-scripts/github-vuln-scanner:latest`

## Usage

```groovy
githubVulnerabilityScan()

githubVulnerabilityScan(projectDir: 'lambda/snapshot_contracts')

githubVulnerabilityScan(
    projectDir: 'lambda/snapshot_contracts',
    repoOwner: 'theorchard',
    excludedPath: 'vagrant',
    skipPhrase: 'skip vulnerability scan',
    ux: 'markdown',
    logLevel: 'debug'
)
```

Key behavior:

- Scans using **Dependabot alerts + GitHub Advisory Database**
- Blocks **newly introduced vulnerable dependencies immediately**
- Posts PR comments **only when blocking vulnerabilities are found**
- Mounts workspace as **read-only**
- Default PR comment format is **table**; use `ux: 'markdown'` for native GitHub Markdown rendering