{"id":50661915,"url":"https://github.com/arpahls/gatekeeper","last_synced_at":"2026-06-08T03:04:19.598Z","repository":{"id":356498303,"uuid":"1232779241","full_name":"ARPAHLS/gatekeeper","owner":"ARPAHLS","description":"Mission-critical access gatekeeper using face verification and emotion-risk policy checks.","archived":false,"fork":false,"pushed_at":"2026-05-08T09:58:35.000Z","size":2203,"stargazers_count":2,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-08T11:34:52.405Z","etag":null,"topics":["access-control","arpa","biometrics","deepface","emotion-analysis","face-verification","mission-critical","opencv","python","security","tensorflow"],"latest_commit_sha":null,"homepage":"https://arpacorp.net","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ARPAHLS.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-08T09:04:05.000Z","updated_at":"2026-05-08T10:24:30.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ARPAHLS/gatekeeper","commit_stats":null,"previous_names":["arpahls/gatekeeper"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/ARPAHLS/gatekeeper","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ARPAHLS%2Fgatekeeper","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ARPAHLS%2Fgatekeeper/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ARPAHLS%2Fgatekeeper/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ARPAHLS%2Fgatekeeper/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ARPAHLS","download_url":"https://codeload.github.com/ARPAHLS/gatekeeper/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ARPAHLS%2Fgatekeeper/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34046005,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-08T02:00:07.615Z","response_time":111,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["access-control","arpa","biometrics","deepface","emotion-analysis","face-verification","mission-critical","opencv","python","security","tensorflow"],"created_at":"2026-06-08T03:04:18.799Z","updated_at":"2026-06-08T03:04:19.591Z","avatar_url":"https://github.com/ARPAHLS.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# Mission-Critical Access Gatekeeper\n\n**Emotion Policy + Face Verification for High-Risk Operations**\n\n[![Python](https://img.shields.io/badge/python-3.11%2B-bdd7ff?style=flat-square)](https://www.python.org/)\n[![DeepFace](https://img.shields.io/badge/deepface-0.0.99+-cfe8d6?style=flat-square)](https://github.com/serengil/deepface)\n[![UseCase](https://img.shields.io/badge/use_case-mission_critical_access-f4d7ff?style=flat-square)](#use-cases)\n[![License](https://img.shields.io/badge/license-MIT-f8e7c9?style=flat-square)](LICENSE)\n\nA DeepFace-based security framework that grants access only when identity verification and emotional-risk policy checks both pass.\n\n\u003cimg src=\"docs/images/gatekeeper-scan.png?v=2\" alt=\"Live face scan with emotion overlay\" width=\"820\" /\u003e\n\n\u003c/div\u003e\n\n- [About](#about)\n- [Architecture](#architecture)\n- [Quick Start](#quick-start)\n- [Notebook Demo](#notebook-demo)\n- [Use Cases](#use-cases)\n- [Why Emotion Gating Matters](#why-emotion-gating-matters)\n- [Security Rules](#security-rules)\n- [Documentation](#documentation)\n- [Contributing](#contributing)\n\nDesigned for high-impact environments, this project helps teams prototype emotion-aware access control with deterministic decisions and auditable outcomes.\n\n## About\n\nThis repository demonstrates how to secure critical gateways using:\n- face verification against a reference image or admin pool with multi-frame identity consensus,\n- emotion classification with threshold + weighted policy,\n- strict 2/2 authorization rule before protected action execution,\n- multi-frame emotion voting with bounded retries and timeout handling.\n\n## Architecture\n\n1. Capture live frame from camera.\n2. Verify identity against reference image and/or admin pool.\n3. Analyze emotions and evaluate policy (`blocked_emotions`, weights, threshold).\n4. If identity and emotion pass, grant access to the protected resource.\n5. Write structured audit event for every decision.\n\nIdentity and emotion use separate thresholds:\n- identity uses `identity.distance_threshold`,\n- emotion uses `emotion.threshold`.\n\n```mermaid\nflowchart TD\n    start[Access request] --\u003e capture[Capture live frames]\n    capture --\u003e identity[Identity consensus check]\n    identity --\u003e identity_ok{Identity passed}\n    identity_ok -- No --\u003e denied[ACCESS DENIED]\n    identity_ok -- Yes --\u003e emotion[Emotion policy check]\n    emotion --\u003e emotion_ok{Emotion policy passed}\n    emotion_ok -- No --\u003e denied\n    emotion_ok -- Yes --\u003e granted[ACCESS GRANTED]\n```\n\n## Quick Start\n\n### 1) Create environment\n\nPrimary runtime (Python 3.13):\n\n```powershell\npy -3.13 -m venv .venv\n.\\.venv\\Scripts\\Activate.ps1\npython -m pip install -r requirements.txt\n```\n\nNote: on some Python 3.13 TensorFlow/DeepFace setups, `tf-keras` is required and is included in `requirements.txt`.\n\nFallback runtime when backend wheels fail:\n\n```powershell\npy -3.12 -m venv .venv-fallback\n.\\.venv-fallback\\Scripts\\Activate.ps1\npython -m pip install -r requirements-fallback.txt\n```\n\n### 2) Configure runtime\n\n`config.yaml` is auto-created on first run if it does not exist.\n\n### 3) Run terminal app\n\n```powershell\npython scripts/run_terminal.py --config-path config.yaml\n```\n\nThe terminal flow is now:\n- Step 1: identity source setup,\n- Step 2: choose advanced configuration (`yes` to customize, `no` to use tuned production defaults).\n\nDefault non-advanced profile is optimized for speed:\n- identity consensus: 5 frames / 2 matches required,\n- emotion voting: 3 frames per batch, up to 2 batches.\n\nRuntime output includes stage-level results:\n- Identity check: pass/fail details\n- Emotion check: pass/fail details\n- Final decision: 2/2 pass or deny\n\nExample terminal configuration and runtime view:\n\n![Gatekeeper terminal flow](docs/images/gatekeeper-terminal.png)\n\n### First-run model weights\n\nOn first identity verification run, DeepFace may try downloading `vgg_face_weights.h5` (used by `VGG-Face`) into:\n\n`C:\\Users\\\u003cyour_user\u003e\\.deepface\\weights\\vgg_face_weights.h5`\n\nIf automatic download fails, run:\n\n```powershell\ncurl.exe -L \"https://github.com/serengil/deepface_models/releases/download/v1.0/vgg_face_weights.h5\" -o \"$env:USERPROFILE\\.deepface\\weights\\vgg_face_weights.h5\"\n```\n\nIf your network blocks large downloads from GitHub, download the same URL in your browser and place the file at the same path.\n\nOn first emotion analysis run, DeepFace may also download `facial_expression_model_weights.h5`.  \nAfter first-time downloads complete, subsequent runs are significantly faster.\n\nTensorFlow startup logs are suppressed by default in launcher, but some backend messages may still appear depending on platform/runtime.\n\n### Windows Unicode path note (`img2_path` errors)\n\nOn some Windows setups, OpenCV can fail reading image paths containing non-ASCII characters (for example Greek folder names), which may surface as:\n\n- `Exception while processing img2_path`\n\nThe framework includes a Unicode-safe fallback loader (`numpy.fromfile` + `cv2.imdecode`) for reference/admin images.  \nIf you still see path-related failures, verify file readability and consider using an ASCII-only path for source images.\n\n## Notebook Demo\n\nOpen `notebooks/security_framework_demo.ipynb` to run the interactive demo with widgets for:\n- identity source,\n- blocked emotions,\n- identity consensus tuning (`frames_per_check`, `min_matches_required`, `distance_threshold`),\n- emotion threshold + voting controls (`frames_per_batch`, `max_batches`),\n- camera window toggle,\n- resource naming and gated authorization flow.\n\n## Use Cases\n\n- Physical access control for restricted spaces.\n- Access to privileged databases, tools, or microservices.\n- Mission-critical infrastructure operations.\n- Financial signing keys and sensitive document systems.\n- AI inference gateways (optional example, not the primary focus).\n\n## Why Emotion Gating Matters\n\nBiometric identity confirms who requests access.  \nEmotional risk analysis helps evaluate whether the person should proceed right now.\n\nIn high-impact environments, an otherwise authorized operator may pass face verification while still being in a compromised state, for example under coercion (such as being forced to authenticate) or severe distress (for example fear, panic, or aggression after a major personal conflict). This framework adds an emotional-risk gate to reduce approvals during those moments, helping protect critical infrastructure, high-value financial operations, and other irreversible systems where temporary instability can create outsized risk.\n\nExample output after a successful gated decision:\n\n![Gatekeeper success output](docs/images/gatekeeper-success.png)\n\n## Extensibility\n\n- Add liveness detection and anti-spoofing.\n- Add additional biometrics (voice, token, geofencing, hardware keys).\n- Add policy profiles by environment and risk level.\n- Attach a custom action executor for any protected workflow.\n\n## Security Rules\n\nAccess is granted only when:\n- identity verification succeeds, and\n- weighted blocked-emotion score stays below threshold.\n\nAll denied decisions return deterministic reason messages.\n\nIf a stable emotional classification is not reached after configured batches, access is denied with guidance to retry under better camera/visibility conditions.\n\n## Documentation\n\n- [Architecture](docs/architecture.md)\n- [Configuration](docs/configuration.md)\n- [Examples](docs/examples.md)\n- [Troubleshooting](docs/troubleshooting.md)\n\n## Contributing\n\nContributions are welcome for policy modules, biometric extensions, and UI improvements.\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for contribution workflow, standards, and PR checklist.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farpahls%2Fgatekeeper","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Farpahls%2Fgatekeeper","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farpahls%2Fgatekeeper/lists"}