Initial commit..

Author: pringlized

.github/workflows/ci.yml

@@ -0,0 +1,58 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    name: test (py${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e '.[dev]'
+
+      - name: Lint
+        run: ruff check
+
+      - name: Test
+        run: pytest -v
+
+  docker:
+    name: docker build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Build image
+        run: docker build -t glassglyph-scanner:ci .
+
+      - name: Run health check
+        run: |
+          docker run -d --name glassglyph -p 8080:8080 glassglyph-scanner:ci
+          for i in {1..30}; do
+            if curl -sf http://localhost:8080/health > /dev/null; then
+              echo "service healthy"
+              exit 0
+            fi
+            sleep 1
+          done
+          echo "service did not become healthy"
+          docker logs glassglyph
+          exit 1

.github/workflows/docs.yml

@@ -0,0 +1,28 @@
+name: Deploy docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - ".github/workflows/docs.yml"
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install docs dependencies
+        run: pip install mkdocs>=1.6 mkdocs-material>=9.5
+
+      - name: Build and deploy
+        run: mkdocs gh-deploy --force --clean

.gitignore

@@ -0,0 +1,18 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+.eggs/
+dist/
+build/
+.pytest_cache/
+.ruff_cache/
+.venv/
+venv/
+.env
+.coverage
+htmlcov/
+*.log
+.DS_Store
+site/
+.pytest_cache/

Dockerfile

@@ -0,0 +1,20 @@
+FROM python:3.12-slim
+
+WORKDIR /app
+
+# Install build deps first so this layer caches well
+COPY pyproject.toml README.md LICENSE ./
+COPY src/ ./src/
+
+RUN pip install --no-cache-dir '.[server]'
+
+# Run as non-root
+RUN useradd --system --uid 1000 glassglyph-scanner && chown -R glassglyph-scanner /app
+USER glassglyph-scanner
+
+EXPOSE 8080
+
+HEALTHCHECK --interval=30s --timeout=3s --start-period=5s \
+  CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:8080/health', timeout=2).read()"
+
+CMD ["uvicorn", "glassglyph-scanner.server:app", "--host", "0.0.0.0", "--port", "8080"]

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jim Pringle
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,230 @@
+# Glassglyph Scanner
+
+**A reference scanner for invisible unicode and homoglyph attacks on text-based systems.**
+
+In March 2026, the Glassworm campaign compromised 151+ GitHub repositories, npm packages, and VS Code extensions by smuggling malicious code inside invisible Unicode characters — text that renders as zero pixels in every editor, terminal, code review tool, and browser. The same class of attack works against RAG pipelines, LLM agents, email, chat, and any system that ingests text and later retrieves it as context.
+
+Glassglyph Scanner scans text for three attack classes:
+
+1. **Invisible unicode encoding** — Glassworm's substitution cipher (variation selectors U+FE00–FE0F and U+E0100–E01EF) plus tag characters that map 1:1 to printable ASCII.
+2. **Bidi override attacks** — control characters that visually reorder text (`safe.txt` → `safe[RLO]txt.exe`).
+3. **Homoglyph substitution** — Cyrillic and Greek characters replacing visually identical Latin letters (`аnthropic.com` with Cyrillic `а`).
+
+Cost: **under a millisecond per document**. Pure string iteration, zero external dependencies in the core library, zero network I/O, zero LLM inference.
+
+---
+
+## Try it in 30 seconds
+
+**Option 1 — Docker:**
+
+```bash
+git clone https://github.com/pringlized/glassglyph-scanner.git
+cd glassglyph-scanner
+docker compose up -d
+curl -X POST http://localhost:8080/scan \
+  -H 'Content-Type: application/json' \
+  -d '{"content":"visit dоcs.аnthropic.com for the API"}'
+```
+
+Expected response: the scanner flags the Cyrillic `о` and `а` as a medium-severity homoglyph finding.
+
+**Option 2 — Python:**
+
+```bash
+pip install -e '.[all]'
+python -c "from glassglyph_scanner import sanitize; r = sanitize('visit dоcs.аnthropic.com'); print(r.findings[0])"
+```
+
+**Option 3 — CLI:**
+
+```bash
+pip install -e '.[cli]'
+echo 'visit dоcs.аnthropic.com' | glassglyph-scanner scan -
+# exit 1 → findings present (flagged, not blocked)
+
+echo 'plain text' | glassglyph-scanner scan -
+# exit 0 → clean
+```
+
+---
+
+## Why this matters
+
+Traditional supply-chain attacks need a decoder at the execution site. **RAG pipelines are different — the LLM is both target and decoder.** When a poisoned item is retrieved as agent context:
+
+1. The agent reads it as knowledge
+2. LLMs tokenize at the byte level — invisible characters are not invisible to the model
+3. The model may follow instructions encoded in them
+4. The item was embedded and clustered with legitimate knowledge, so it has full semantic credibility
+
+**Ingestion-time scanning is the only viable enforcement point.** Once the content is embedded, it's semantically indistinguishable from clean knowledge.
+
+See [`docs/threat-model.md`](docs/threat-model.md) for the full threat model.
+
+---
+
+## Detection rules
+
+| Range | Name | Severity | Action |
+|---|---|---|---|
+| `U+FE00`–`U+FE0F` | Variation selectors | **Critical** | Block |
+| `U+E0100`–`U+E01EF` | Supp. variation selectors | **Critical** | Block |
+| `U+E0020`–`U+E007F` | Tag characters | **Critical** | Block |
+| `U+200B`–`U+200F` | Zero-width / bidi marks | High | Strip |
+| `U+202A`–`U+202E` | Bidi overrides | High | Strip |
+| `U+2060`–`U+2064` | Invisible math operators | High | Strip |
+| `U+FEFF` (non-BOM position) | Zero-width no-break space | High | Strip |
+| `U+E0001` | Language tag (deprecated) | High | Strip |
+| Mixed-script word w/ confusable | e.g. Cyrillic `а` in `аnthropic` | Medium | Flag |
+| Mixed-script word w/o confusable | e.g. Cyrillic `ж` in `aжb` | Low | Flag |
+
+**Critical = block:** no legitimate text contains these ranges. Their presence indicates an encoding attack. Reject the document.
+
+**High = strip:** these characters have narrow legitimate uses (Arabic text shaping, emoji sequences) but are dangerous in knowledge items. Characters are removed, the document proceeds with sanitized text.
+
+**Medium/Low = flag:** homoglyphs can appear in legitimate multilingual content. The finding is reported; the calling system decides whether to quarantine.
+
+Full rule reference in [`docs/detection-rules.md`](docs/detection-rules.md).
+
+---
+
+## Library API
+
+```python
+from glassglyph_scanner import sanitize
+
+result = sanitize("some text")
+
+if result.has_critical_findings:
+    # BLOCK — invisible encoding detected
+    log_and_reject(result.findings)
+elif result.was_modified:
+    # STRIP — use sanitized content going forward
+    process(result.sanitized_content)
+elif result.findings:
+    # FLAG — content unmodified, review findings
+    queue_for_review(result.findings)
+else:
+    # CLEAN — proceed
+    process(result.sanitized_content)
+```
+
+`SanitizationResult` fields:
+
+- `clean: bool` — true iff no findings
+- `sanitized_content: str` — content with high-severity chars removed
+- `findings: list[SanitizationFinding]` — each with `threat_category`, `severity`, `description`, `character_ranges`, `action_taken`
+- `has_critical_findings: bool` — signal to block
+- `was_modified: bool` — true iff sanitized_content differs from input
+- `scan_duration_ms: float`
+
+---
+
+## HTTP API
+
+```
+POST /scan             body: {"content": "..."}
+GET  /health           liveness probe
+GET  /                 landing page
+GET  /docs             OpenAPI UI
+```
+
+Full reference: [`docs/api.md`](docs/api.md)
+
+---
+
+## CLI
+
+```bash
+glassglyph-scanner scan FILE           # scan a file
+glassglyph-scanner scan -              # scan stdin
+glassglyph-scanner scan FILE --json    # machine-readable output
+glassglyph-scanner scan FILE --quiet   # exit code only
+glassglyph-scanner --version
+```
+
+Exit codes:
+- `0` — clean
+- `1` — findings present (stripped or flagged)
+- `2` — critical findings (block)
+- `64` — usage error
+
+---
+
+## Installation
+
+```bash
+# Core library only (zero dependencies)
+pip install glassglyph-scanner
+
+# With CLI
+pip install 'glassglyph-scanner[cli]'
+
+# With HTTP service
+pip install 'glassglyph-scanner[server]'
+
+# Everything
+pip install 'glassglyph-scanner[all]'
+
+# Development (tests, linting)
+pip install -e '.[dev]'
+```
+
+---
+
+## Examples
+
+The `examples/` directory contains:
+
+- `clean.txt` — normal content
+- `glassworm_attack.txt` — a pre-built Glassworm-encoded payload
+- `homoglyph_url_spoof.txt` — URL with Cyrillic substitutions
+- `zero_width_strip.txt` — zero-width chars interspersed in visible text
+- `generate_glassworm.py` — generate your own invisible payloads
+
+Run all examples:
+
+```bash
+for f in examples/*.txt; do
+  echo "=== $f ==="
+  glassglyph-scanner scan "$f"
+done
+```
+
+---
+
+## What this is NOT
+
+- **Not a semantic/intent scanner.** Glassglyph Scanner does character-level detection only. Attacks using natural-language prompt injection in plain ASCII are outside its scope — that class of attack requires LLM inference to detect.
+- **Not a content filter.** This scans for encoding-based attacks, not for policy violations, PII, or toxic content.
+- **Not a replacement for TLS, authentication, rate limiting, or other perimeter controls.**
+
+For the full two-gate defense model (character gate + intent gate), see `docs/threat-model.md`.
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/pringlized/glassglyph-scanner.git
+cd glassglyph-scanner
+pip install -e '.[dev]'
+pytest                  # run all tests
+ruff check              # lint
+uvicorn glassglyph_scanner.server:app --reload  # serve locally
+```
+
+---
+
+## License
+
+MIT. See `LICENSE`.
+
+---
+
+## Credits
+
+Research basis: Aikido Security's March 2026 Glassworm writeup, Unicode Consortium TR39 confusables data, and community security research on invisible-unicode supply-chain attacks.
+
+Built as a reference implementation from the Mens Altera ingestion pipeline's Gate 1 character sanitization layer.

docker-compose.yml

@@ -0,0 +1,14 @@
+services:
+  glassglyph-scanner:
+    build: .
+    container_name: glassglyph-scanner
+    ports:
+      - "8080:8080"
+    restart: unless-stopped
+    # Read-only root FS since we don't write anything
+    read_only: true
+    # Drop all capabilities — the service doesn't need them
+    cap_drop:
+      - ALL
+    security_opt:
+      - no-new-privileges:true