Skip to content

vecna/ghostati

BranchesTags

Repository files navigation

Ghostmaxxing

Unit Test Coverage

Docs Source

Ghostmaxxing is a static, browser-side Web AR laboratory for designing and testing face-obfuscation overlays against face-detection and face-recognition pipelines.

The project combines webcam capture, face-api.js, MediaPipe Tasks Vision, canvas rendering, local descriptor storage, and a plugin system for custom Ghostyles: 2D or 3D face overlays that can be tested against recognition behavior in real time.

Primary links:

Central field-reporting resource: if you know of a place where facial recognition is being deployed, tested, procured, or hidden in public-space infrastructure, use the NINA submission node: Raccontacelo. Reports about supplier, technology, data access, deployment context, limits, and abuses are project inputs, not side notes.

What the app does

 webcam ──► detector ──► landmarks ──► overlay renderer
    │                         │                │
    └──── baseline face DB ◄──┴──── compare ◄──┘

The app is designed around a simple experimental loop:

  1. Start the webcam in a modern browser.
  2. Load face-detection and landmark models.
  3. Save a local baseline descriptor for a consenting test face.
  4. Apply a Ghostyle overlay to the live video/canvas layer.
  5. Re-run detection and recognition against the saved descriptor.
  6. Observe whether the pipeline still detects the face, extracts landmarks, and matches the baseline.

Core capabilities:

Runtime architecture

 ghostati.html
   ├─ @vladmandic/face-api
   ├─ @mediapipe/tasks-vision
   ├─ scripts/main.js
   │   ├─ camera.js
   │   ├─ engine.js
   │   ├─ db.js
   │   ├─ dom.js
   │   └─ ghostyles-manager.js
   ├─ ghostyles.json
   └─ ghostyles/*.js

The project is a static web app: there is no production build step required to open the interface locally. The browser loads HTML, CSS, JavaScript modules, model assets, and plugin manifests.

Important local entry points:

Runtime external dependencies visible from the HTML/config layer:

For workshops or higher-risk demos, prefer self-hosting model and library assets instead of relying on third-party CDNs.

Install and run locally

 clone ──► install dev deps ──► static server ──► browser + webcam

Clone the repository:

git clone https://github.com/vecna/ghostati.git
cd ghostati

Install development dependencies:

npm install

Serve the directory with any local static server:

npx http-server .
# or
python3 -m http.server 8000

Open the app:

http://localhost:8000/ghostati.html

Open the landing page:

http://localhost:8000/

Ghostyles plugin API

 landmarks + box + canvas context
          │
          ▼
      ghostyle module
          │
          ▼
   live overlay + diagnostic pass

A Ghostyle is a JavaScript module that draws an overlay anchored to a detected face. It can be local or loaded through a manifest.

Start from ghostyles/00-template.js, then add the file to ghostylist.json. Existing 2D examples include:

A minimal 2D plugin shape:

/**
 * @name Example Ghostyle
 * @engine faceapi
 */
export function onInit() {
  return 'loaded';
}

export function onDraw(ctx, landmarks, box) {
  ctx.save();
  // Draw against landmarks and detection box here.
  ctx.restore();
}

export function onClear(ctx) {
  ctx.clearRect(0, 0, ctx.canvas.width, ctx.canvas.height);
}

3D/MediaPipe-oriented examples live in:

Register them in ghostylist3d.json.

Testing and generated docs

 unit tests ──► coverage
 e2e tests  ──► browser flows
 jsdoc      ──► docs/

Package scripts:

npm run test:unit
npm run test:unit -- --coverage
npm run test:e2e
npm run docs

Testing stack:

Relevant test directories:

Privacy, data, and limitations

 browser storage
    ├─ descriptors
    ├─ preferences
    └─ test state
 external network
    ├─ fonts
    ├─ CDN libraries
    └─ model weights

The app is designed to keep biometric test data local to the browser interface. Face descriptors and related state are stored locally, not posted to a central server by the default app flow.

Technical caveats:

  • webcam access is controlled by the browser permission model;
  • local descriptors may persist in IndexedDB/local browser storage until cleared;
  • screenshots, recordings, and exports should be treated as sensitive biometric-adjacent material;
  • CDN-loaded libraries and model files still create external network requests;
  • detection failure, landmark instability, and match failure are different outcomes and should not be collapsed into “anonymity”;
  • a Ghostyle that affects this browser pipeline may not affect another face-recognition system.

Use consenting test subjects. Do not represent experimental overlays as operational safety guarantees.

Field reports: public-space face recognition

 observe ──► document ──► submit ──► update resistance research

Ghostmaxxing is also connected to a field-reporting workflow. The landing page now treats the NINA reporting node as a central project resource:

Raccontacelo: segnala un possibile uso di riconoscimento facciale nello spazio pubblico

Useful report details include:

  • location and institutional context;
  • supplier or vendor name;
  • visible hardware or software clues;
  • procurement documents, signage, screenshots, or public records;
  • who appears to access the data;
  • retention, oversight, and abuse risks;
  • whether the system is detection-only, identification, verification, watchlist matching, analytics, or unclear.

The point is to turn deployments into inspectable evidence: claims, vendors, interfaces, procurement, sensors, data flows, and affected communities.

References dataset

 REFERENCES.json ──► timeline / exhibition / research context
 PROMPT-REFERENCES-UPDATE.txt ──► repeatable curation rules

REFERENCES.json is a curated dataset of artistic, research, and activism-adjacent references around face obfuscation, adversarial appearance design, makeup-based attacks, physical-world adversarial vision, and sensor disruption.

The update protocol in PROMPT-REFERENCES-UPDATE.txt keeps the file deduplicated, sorted, and stable. It requires canonical links, local preview-image paths, stable slugs, and a closeness score from 1 to 100.

Current reference links:

Contributing

 small patch
 clear test
 stable plugin API
 documented behavior

Good contributions include:

  • new Ghostyles with clear metadata and reproducible test notes;
  • tighter unit coverage around renamed/refactored functions;
  • e2e scenarios for detection, baseline saving, overlay switching, and match-state transitions;
  • CDN self-hosting options;
  • clearer model-loading failure states;
  • accessibility and mobile UI improvements;
  • better documentation for faceapi vs mediapipe Ghostyle engines;
  • additions to REFERENCES.json following PROMPT-REFERENCES-UPDATE.txt.

Please keep claims narrow and technical: say which model, browser, lighting, camera, and threshold produced which result.

Last commit: 85f9100 – internationalization added, three languages

Recent changes

  • 85f9100 internationalization added, three languages
  • 697c972 JSdoc improvements
  • 1a49dea added condition for face not found during composite analysis
  • 3b32d40 deleted some dead code and improved UT
  • b09f30a removal of duplicated code

About

Ghòstati! diventa un fantasma agli occhi del riconoscimento facciale

sindacato.nina.watch/ghostati

Topics

computer-vision face-recognition adversarial dazzle

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

2 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages