Integration Guide

Step 1 -- Add the workflow file

Create .github/workflows/binshield.yml:

name: Binary Dependency Check
on: [pull_request]

jobs:
  binshield:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: ashlrai/binshield-action@v1
        with:
          fail-on: high
          github-token: ${{ secrets.GITHUB_TOKEN }}

Step 2 -- Add an API key (optional)

Store your BinShield API key as a repository secret named BINSHIELD_API_KEY:

      - uses: ashlrai/binshield-action@v1
        with:
          api-key: ${{ secrets.BINSHIELD_API_KEY }}
          fail-on: high
          github-token: ${{ secrets.GITHUB_TOKEN }}

Step 3 -- Tune your policy

Set fail-on to critical, high, medium, low, or never:

          fail-on: medium          # block on medium-risk or above
          scan-mode: all-dependencies  # full lockfile audit
          comment-mode: pr-comment     # post results as a PR comment

Search packages

const res = await fetch(
  "https://binshieldapi-production.up.railway.app/packages/search?q=bcrypt"
);
const results = await res.json();
console.log(results);

Submit a scan

const scanRes = await fetch(
  "https://binshieldapi-production.up.railway.app/scans",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${process.env.BINSHIELD_API_KEY}`,
    },
    body: JSON.stringify({
      ecosystem: "npm",
      package: "bcrypt",
      version: "6.0.0",
    }),
  }
);
const { scanId } = await scanRes.json();

Poll for results

async function pollScan(scanId, intervalMs = 1500, timeoutMs = 120000) {
  const start = Date.now();
  while (Date.now() - start < timeoutMs) {
    const res = await fetch(
      `https://binshieldapi-production.up.railway.app/scans/${scanId}`,
      { headers: { Authorization: `Bearer ${process.env.BINSHIELD_API_KEY}` } }
    );
    const data = await res.json();
    if (data.status === "complete") return data;
    if (data.status === "error") throw new Error(data.error);
    await new Promise((r) => setTimeout(r, intervalMs));
  }
  throw new Error("Scan timed out");
}

const result = await pollScan(scanId);
console.log(result.riskLevel, result.riskScore);

Search packages

import requests

res = requests.get(
    "https://binshieldapi-production.up.railway.app/packages/search",
    params={"q": "bcrypt"},
)
print(res.json())

Submit and poll a scan

import os, time, requests

API = "https://binshieldapi-production.up.railway.app"
HEADERS = {"Authorization": f"Bearer {os.environ['BINSHIELD_API_KEY']}"}

# Submit
scan = requests.post(
    f"{API}/scans",
    json={"ecosystem": "npm", "package": "bcrypt", "version": "6.0.0"},
    headers=HEADERS,
).json()

scan_id = scan["scanId"]

# Poll
timeout = time.time() + 120
while time.time() < timeout:
    result = requests.get(f"{API}/scans/{scan_id}", headers=HEADERS).json()
    if result["status"] == "complete":
        print(result["riskLevel"], result["riskScore"])
        break
    if result["status"] == "error":
        raise RuntimeError(result["error"])
    time.sleep(1.5)
else:
    raise TimeoutError("Scan timed out")

GitHub Actions (full example)

name: Binary Dependency Check
on: [pull_request]

jobs:
  binshield:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: ashlrai/binshield-action@v1
        with:
          api-key: ${{ secrets.BINSHIELD_API_KEY }}
          fail-on: high
          scan-mode: native-only
          comment-mode: both
          github-token: ${{ secrets.GITHUB_TOKEN }}

GitLab CI

binshield:
  stage: test
  image: node:20
  script:
    - npx @binshield/cli scan --fail-on high --format json > binshield-report.json
  artifacts:
    reports:
      security: binshield-report.json
  rules:
    - if: $CI_MERGE_REQUEST_ID

CircleCI

version: 2.1

jobs:
  binshield:
    docker:
      - image: cimg/node:20.0
    steps:
      - checkout
      - run:
          name: BinShield scan
          command: npx @binshield/cli scan --fail-on high

workflows:
  security:
    jobs:
      - binshield

BinShield generates CycloneDX 1.5 SBOMs with binary-level detail. Export and save for compliance workflows:

# Export a single package SBOM
curl -s \
  "https://binshieldapi-production.up.railway.app/packages/npm/bcrypt/versions/6.0.0/sbom" \
  | jq .

# Save for audit
curl -s \
  "https://binshieldapi-production.up.railway.app/packages/npm/bcrypt/versions/6.0.0/sbom" \
  -o bcrypt-6.0.0-sbom.json

# Extract component list
curl -s \
  "https://binshieldapi-production.up.railway.app/packages/npm/bcrypt/versions/6.0.0/sbom" \
  | jq '.components[] | {name, version, type}'