Integration

CI/CD Integration

Gate deployments on Sigil scan results. Block PRs that introduce risky dependencies. Automated supply chain security in every pipeline.

GitHub Actions

Add Sigil to any GitHub Actions workflow. Scans run on every push or pull request and block merges when findings exceed your threshold.

Basic setup

.github/workflows/sigil.yml

1name: Sigil Security Scan
2on:
3  pull_request:
4  push:
5    branches: [main]
6
7jobs:
8  sigil:
9    runs-on: ubuntu-latest
10    steps:
11      - uses: actions/checkout@v4
12
13      - name: Run Sigil scan
14        uses: NOMARJ/sigil@main
15        with:
16          path: "."
17          threshold: medium
18          fail-on-findings: true

Inputs

Input	Default	Description
path	.	Directory to scan
threshold	medium	Minimum verdict level to trigger a failure
fail-on-findings	true	Exit with non-zero code when findings exceed threshold
format	text	Output format: `text`, `json`, `sarif`
phases	all	Comma-separated list of phases to run, or `all`
upload-sarif	false	Upload SARIF results to GitHub Code Scanning
sigil-token	—	API token for cloud threat intelligence (Pro/Team)

Outputs

Output	Description
verdict	Scan verdict: `low`, `medium`, `high`, `critical`
score	Numeric risk score
findings-count	Total number of findings detected
report-path	Path to the generated report file

SARIF upload

Enable upload-sarif to push results to GitHub Code Scanning. Findings appear as inline annotations on pull requests.

.github/workflows/sigil-sarif.yml

1name: Sigil Security Scan
2on:
3  pull_request:
4  push:
5    branches: [main]
6
7jobs:
8  sigil:
9    runs-on: ubuntu-latest
10    steps:
11      - uses: actions/checkout@v4
12
13      - name: Run Sigil scan
14        uses: NOMARJ/sigil@main
15        with:
16          path: "."
17          threshold: medium
18          fail-on-findings: true
19          upload-sarif: true

SARIF integration

Upload SARIF results to GitHub Advanced Security for inline PR annotations. Findings appear directly on the changed files in your pull request.

Scan only changed files

Speed up PR scans by only analyzing files that changed in the pull request.

.github/workflows/sigil-diff.yml

1name: Sigil Diff Scan
2on:
3  pull_request:
4
5jobs:
6  sigil:
7    runs-on: ubuntu-latest
8    steps:
9      - uses: actions/checkout@v4
10        with:
11          fetch-depth: 0
12
13      - name: Get changed files
14        id: changed
15        run: |
16          echo "files=$(git diff --name-only origin/${GITHUB_BASE_REF} HEAD | tr '\n' ',')" >> $GITHUB_OUTPUT
17
18      - name: Run Sigil scan on changed files
19        uses: NOMARJ/sigil@main
20        with:
21          path: ${{ steps.changed.outputs.files }}
22          threshold: medium
23          fail-on-findings: true

Block merge on high-risk

Add the Sigil scan as a required status check in your branch protection rules. PRs cannot merge until the scan passes.

Required status check

Go to Settings → Branches → Branch protection rules and add the Sigil job name (e.g. sigil) as a required status check. PRs with HIGH or CRITICAL findings will be blocked from merging.

Authenticated scans

Pass your Sigil API token for cloud threat intelligence lookups (Pro and Team plans).

.github/workflows/sigil-auth.yml

1- name: Run Sigil scan
2  uses: NOMARJ/sigil@main
3  with:
4    path: "."
5    threshold: medium
6    fail-on-findings: true
7    sigil-token: ${{ secrets.SIGIL_TOKEN }}

GitLab CI

Include the remote Sigil template to add scanning to any GitLab pipeline. Scan results are stored as job artifacts.

Basic setup

.gitlab-ci.yml

1include:
2  - remote: "https://raw.githubusercontent.com/NOMARJ/sigil/main/.gitlab/sigil.yml"
3
4sigil-scan:
5  stage: test
6  variables:
7    SIGIL_SCAN_PATH: "."
8    SIGIL_THRESHOLD: "medium"
9    SIGIL_FAIL_ON_FINDINGS: "true"
10    SIGIL_FORMAT: "json"
11  artifacts:
12    paths:
13      - sigil-report.json
14    when: always

Variables

Variable	Default	Description
SIGIL_SCAN_PATH	.	Directory to scan
SIGIL_THRESHOLD	medium	Minimum verdict level to trigger a failure
SIGIL_FAIL_ON_FINDINGS	true	Exit with non-zero code when findings exceed threshold
SIGIL_FORMAT	text	Output format: `text`, `json`, `sarif`
SIGIL_TOKEN	—	API token for cloud threat intelligence (Pro/Team)

Generic CI/CD

Sigil works in any CI environment that can run shell commands — Jenkins, CircleCI, Bitbucket Pipelines, or anything else. Three steps: install, scan, gate.

1. Install

bash

# Install via shell script
curl -sSL https://sigilsec.ai/install.sh | sh

# Or pull the Docker image
docker pull ghcr.io/nomarj/sigil:latest

2. Run scan

bash

sigil scan . --format json > sigil-report.json

3. Exit codes

Use exit codes to gate pipeline stages. Each verdict maps to a specific exit code.

Exit Code	Verdict	Pipeline Action
0	LOW RISK	Pipeline passes
4	LOW RISK	Pass with warning
3	MEDIUM RISK	Pass or fail (configurable)
2	HIGH RISK	Fail pipeline
1	CRITICAL RISK	Fail pipeline

Exit code gate script

bash

sigil scan . --format json > sigil-report.json
EXIT_CODE=$?

if [ $EXIT_CODE -ge 2 ]; then
  echo "Sigil detected HIGH or CRITICAL findings. Failing pipeline."
  exit 1
fi

echo "Scan passed (exit code: $EXIT_CODE)"
exit 0

Jenkins

Declarative pipeline example with Sigil scan and artifact archiving.

Jenkinsfile

1pipeline {
2    agent any
3
4    stages {
5        stage('Checkout') {
6            steps {
7                checkout scm
8            }
9        }
10        stage('Install Sigil') {
11            steps {
12                sh 'curl -sSL https://sigilsec.ai/install.sh | sh'
13            }
14        }
15        stage('Sigil Scan') {
16            steps {
17                sh '''
18                    sigil scan . --format json > sigil-report.json
19                    EXIT_CODE=$?
20                    if [ $EXIT_CODE -ge 2 ]; then
21                        echo "Sigil detected HIGH or CRITICAL findings."
22                        exit 1
23                    fi
24                '''
25            }
26        }
27    }
28    post {
29        always {
30            archiveArtifacts artifacts: 'sigil-report.json', allowEmptyArchive: true
31        }
32    }
33}

CircleCI

CircleCI config with Docker executor, Sigil install, scan, and artifact storage.

.circleci/config.yml

1version: 2.1
2
3jobs:
4  sigil-scan:
5    docker:
6      - image: cimg/base:stable
7    steps:
8      - checkout
9      - run:
10          name: Install Sigil
11          command: curl -sSL https://sigilsec.ai/install.sh | sh
12      - run:
13          name: Run Sigil scan
14          command: |
15            sigil scan . --format json > sigil-report.json
16            EXIT_CODE=$?
17            if [ $EXIT_CODE -ge 2 ]; then
18              echo "Sigil detected HIGH or CRITICAL findings."
19              exit 1
20            fi
21      - store_artifacts:
22          path: sigil-report.json
23          destination: sigil-report
24
25workflows:
26  security:
27    jobs:
28      - sigil-scan

Bitbucket Pipelines

Bitbucket Pipelines config with Sigil scan on every pull request.

bitbucket-pipelines.yml

1image: atlassian/default-image:4
2
3pipelines:
4  pull-requests:
5    '**':
6      - step:
7          name: Sigil Security Scan
8          script:
9            - curl -sSL https://sigilsec.ai/install.sh | sh
10            - sigil scan . --format json > sigil-report.json
11            - EXIT_CODE=$?
12            - |
13              if [ $EXIT_CODE -ge 2 ]; then
14                echo "Sigil detected HIGH or CRITICAL findings."
15                exit 1
16              fi
17          artifacts:
18            - sigil-report.json

Docker-Based CI

Run Sigil as a Docker container for hermetic, reproducible scans in any pipeline.

Volume mount

Mount your workspace into the container and scan it directly.

bash

docker run --rm -v "$(pwd):/workspace" ghcr.io/nomarj/sigil:latest scan /workspace

Multi-stage build

Scan your application as part of a multi-stage Docker build. The scanner stage gates the production image — if findings exceed the threshold, the build fails.

Dockerfile

1# Stage 1: Build
2FROM node:20-alpine AS builder
3WORKDIR /app
4COPY package*.json ./
5RUN npm ci
6COPY . .
7RUN npm run build
8
9# Stage 2: Sigil Scan
10FROM ghcr.io/nomarj/sigil:latest AS scanner
11COPY --from=builder /app /workspace
12RUN sigil scan /workspace --format json > /sigil-report.json
13
14# Stage 3: Production
15FROM node:20-alpine AS production
16WORKDIR /app
17COPY --from=builder /app/dist ./dist
18COPY --from=builder /app/node_modules ./node_modules
19COPY --from=scanner /sigil-report.json ./sigil-report.json
20EXPOSE 3000
21CMD ["node", "dist/index.js"]

Alert Notifications

Configure alerts to notify your team when CI scans detect high-risk or critical findings.

Slack webhook

bash

curl -X POST https://api.sigilsec.ai/v1/settings/alerts \
  -H "Authorization: Bearer $SIGIL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "slack",
    "webhook_url": "https://hooks.slack.com/services/T00/B00/xxxxx",
    "events": ["scan.high", "scan.critical"]
  }'

Email alerts

bash

curl -X POST https://api.sigilsec.ai/v1/settings/alerts \
  -H "Authorization: Bearer $SIGIL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "email",
    "email": "security@yourcompany.com",
    "events": ["scan.high", "scan.critical"]
  }'

Generic webhook

bash

curl -X POST https://api.sigilsec.ai/v1/settings/alerts \
  -H "Authorization: Bearer $SIGIL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "webhook",
    "url": "https://yourcompany.com/webhooks/sigil",
    "secret": "whsec_your_signing_secret",
    "events": ["scan.high", "scan.critical"]
  }'

Alert events

Alert events include scan.high and scan.critical. Alerts fire for any CI scan that produces a matching verdict.

Output Formats

Sigil supports three output formats. Use --format to select the format that fits your pipeline.

Text (default)

Human-readable output with colored verdicts. Best for terminal use and quick triage.

bash

sigil scan . --format text

JSON

Machine-readable JSON output for scripting, dashboards, and CI/CD integration.

bash

sigil scan . --format json

json

1{
2  "verdict": "medium",
3  "score": 14,
4  "findings": [
5    {
6      "severity": "medium",
7      "phase": "code_patterns",
8      "rule": "dynamic-execution",
9      "file": "src/utils/loader.js",
10      "line": 42,
11      "snippet": "eval(atob(encodedPayload))",
12      "weight": 5
13    }
14  ],
15  "files_scanned": 312,
16  "duration_ms": 2140
17}

SARIF

Static Analysis Results Interchange Format (SARIF 2.1.0). Compatible with GitHub Code Scanning, VS Code SARIF Viewer, and other SARIF-compatible tools.

bash

sigil scan . --format sarif > results.sarif

Previous← MCP Server NextSigil Bot →

Need help?

Ask a question in GitHub Discussions or check the troubleshooting guide.

Community Troubleshooting