SETUP

Get started in two steps.

Zero agents run during install.

The scanner runs in your terminal — it never calls an external API during the scan. The Granite Guardian judge step is optional and only activates when you configure watsonx or Ollama.

Install the scanner

Clone the repo and install dependencies from the /scanner folder.

Terminal

git clone https://github.com/yasinfitrah24-tech/subtext.git
cd subtext/scanner
npm install
npm run build

The CLI is now available as node dist/index.js or via npx ts-node src/index.ts.

Scan a repo

Point the scanner at any local directory. It reads every text file and returns a score, verdict, and list of findings.

Scan a cloned repo

# Scan a cloned repo
npx ts-node src/index.ts ../some-repo --verbose

# With the Granite Guardian judge step (requires Ollama or watsonx env vars)
npx ts-node src/index.ts ../some-repo --judge --verbose

# Write clean copies of flagged files to ./clean (originals untouched)
npx ts-node src/index.ts ../some-repo --sanitize ./clean

Exit code 2 means BLOCK — safe for CI pipelines. --sanitize writes a clean copy of each flagged file plus SUBTEXT_CHANGES.md, and never touches the originals.

Use with IBM Bob

Bob’s Security Gate mode treats repo content as data and never as instructions. It runs Subtext automatically and only hands off to Agent mode when the verdict is SAFE.

Bob workflow

# In Bob: switch to Security Gate mode, then:
1. Paste or provide the repo path
2. Bob runs subtext scan automatically
3. Findings surface before any agent reads the files
4. SAFE → continue in Agent mode
   REVIEW/BLOCK → inspect findings first

Optional: Granite Guardian

You don’t need this to try Subtext. The scanner, Clean copy and tests run without any judge, and the Demo page already runs Granite Guardian live on IBM watsonx. Add a judge to the CLI only if you have your own watsonx key or want to run fully offline.

watsonx.ai (cloud, recommended)

Set three env vars (WATSONX_MODEL is optional). The scanner exchanges your API key for an IAM token automatically.

# .env
WATSONX_API_KEY=your-ibm-cloud-api-key
WATSONX_PROJECT_ID=your-project-id
WATSONX_URL=https://us-south.ml.cloud.ibm.com
WATSONX_MODEL=ibm/granite-guardian-3-8b

Ollama (local, offline, ~5 GB download)

Pull granite4.1-guardian:8b-q4_K_M and set OLLAMA_URL.

ollama pull granite4.1-guardian:8b-q4_K_M
# .env
OLLAMA_URL=http://localhost:11434

ℹIf neither provider is configured, the scanner falls back to a cached keyword heuristic and labels results as provider: cached. The live site runs the judge on IBM watsonx (ibm/granite-guardian-3-8b).

CI / pre-merge gate

Add Subtext as a CI step to block BLOCK-verdict PRs before they’re merged.

GitHub Actions example

- name: Scan for prompt injections
  run: |
    cd scanner
    npm ci
    npm run build
    node dist/index.js ../. --verbose
  # Exit code 2 = BLOCK — fails the workflow