{"id":34810624,"url":"https://github.com/balejosg/openpath","last_synced_at":"2026-05-26T17:01:47.620Z","repository":{"id":320550488,"uuid":"1082510470","full_name":"balejosg/Openpath","owner":"balejosg","description":"Auditable open-source core for intentional internet access in education.","archived":false,"fork":false,"pushed_at":"2026-04-29T08:52:14.000Z","size":66669,"stargazers_count":0,"open_issues_count":35,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-29T10:36:52.485Z","etag":null,"topics":["auditability","content-filtering","dns","education","endpoint-management","internet-access-control","school-it","whitelist"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/balejosg.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-10-24T10:52:58.000Z","updated_at":"2026-04-29T08:31:49.000Z","dependencies_parsed_at":"2025-10-24T13:21:57.596Z","dependency_job_id":"05e88034-0236-41ce-b8df-bb66c65569e6","html_url":"https://github.com/balejosg/Openpath","commit_stats":null,"previous_names":["balejosg/whitelist"],"tags_count":535,"template":false,"template_full_name":null,"purl":"pkg:github/balejosg/Openpath","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/balejosg%2FOpenpath","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/balejosg%2FOpenpath/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/balejosg%2FOpenpath/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/balejosg%2FOpenpath/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/balejosg","download_url":"https://codeload.github.com/balejosg/Openpath/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/balejosg%2FOpenpath/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32530176,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-02T01:12:54.858Z","status":"online","status_checked_at":"2026-05-02T02:00:05.923Z","response_time":132,"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":["auditability","content-filtering","dns","education","endpoint-management","internet-access-control","school-it","whitelist"],"created_at":"2025-12-25T12:46:13.419Z","updated_at":"2026-05-26T17:01:47.597Z","avatar_url":"https://github.com/balejosg.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# OpenPath\n\n**Intentional internet for the classroom. Private by design. Open by conviction.**\n\n[![CI](https://github.com/balejosg/openpath/actions/workflows/ci.yml/badge.svg)](https://github.com/balejosg/openpath/actions/workflows/ci.yml)\n[![codecov](https://codecov.io/github/balejosg/openpath/graph/badge.svg)](https://app.codecov.io/github/balejosg/openpath)\n[![License: AGPL-3.0-or-later](https://img.shields.io/badge/License-AGPL--3.0--or--later-blue.svg)](LICENSE)\n\n---\n\n## The Problem\n\nStudents get distracted on computers. Every teacher who has taught in a technology or computer science classroom knows it. **OpenPath is an open-source tool that gives teachers direct control over which websites are available in their classroom, with no telemetry, no browsing data collection, and full transparency.**\n\n## Why Not Just Another Filter?\n\n### No more cat and mouse\n\nMost filters work by **blacklisting**, maintaining an ever-growing list of banned sites. This turns internet management into an exhausting game: students find a new game site, a proxy, or an unblocked social media mirror, and the teacher scrambles to block it. The next day, there is a new one. You are always one step behind.\n\n**OpenPath flips the model.** Instead of banning what is bad, you approve what is needed. If a domain is not on the whitelist, it simply does not exist on that machine. There is no next loophole to discover, no new site to chase, because the default state is _closed_. Students cannot reach distractions because the door was never open in the first place.\n\n### The teacher sets the rules, not IT\n\nCommercial filters are usually managed by the IT department at a school-wide level. One global policy for every class in the building. But a biology teacher and a web development teacher have completely different needs, and a generic filter doesn't know that.\n\nWith OpenPath, **each teacher manages their own classroom's whitelist**. You decide what your students can access, and you can change it between lessons or even mid-class. IT handles the infrastructure; you handle the teaching.\n\n### Unblock a domain in seconds, mid-class\n\nA student needs a resource you didn't anticipate? No need to submit a ticket to IT and wait. The teacher can **add a domain to the whitelist from the dashboard and it takes effect within seconds** while the class is still running. The browser extension also lets students request an unblock that the teacher can approve on the spot. The workflow stays in the classroom, not in a helpdesk queue.\n\n## What OpenPath Does\n\nOpenPath puts **the teacher in control** of internet access in their classroom, not the IT department, not a remote vendor, not a global policy that tries to fit every subject at once. Each teacher defines exactly which websites are available for their class and enforces that decision at the operating system level. If a domain is not on the approved list, it simply does not resolve. No redirect pages, no tracking, no grey areas.\n\n- **Teacher-driven, per-classroom control**: each classroom has its own whitelist, managed by the teacher who knows what the lesson needs.\n- **Whitelist-based, not blacklist-based**: only explicitly approved domains open. Everything else is blocked by default.\n- **Real-time flexibility**: add or remove domains mid-class from the dashboard. Students can request unblocks; teachers approve them instantly.\n- **Endpoint enforcement**: agents on Linux and Windows apply policy through local DNS and firewall rules, not browser plugins alone.\n- **Browser integration**: a Firefox extension shows teachers what is being blocked and lets students request access to sites they need.\n- **Admin dashboard**: a clean web interface where teachers manage their classrooms, approved domains, and schedules.\n\n## Current Limitations\n\nOpenPath is intentionally restrictive while the endpoint and browser-control\nsurface is still maturing:\n\n- The full classroom browser workflow is currently centered on managed Firefox:\n  blocked-page visibility, blocked-path and blocked-subdomain enforcement, and\n  student unblock requests rely on the Firefox extension and native host.\n- Endpoint agents may block unmanaged or unapproved browsers to prevent students\n  from bypassing local DNS and firewall policy. On Windows this includes\n  denying common alternative browsers and portable browsers unless a managed\n  browser path is explicitly supported.\n- On Windows, the managed browser boundary uses AppLocker for standard\n  non-admin student accounts. This is not a browser-only switch: it can also\n  block executables or scripts launched from student-writable locations such as\n  Downloads, Desktop, or Temp, and selected bypass tools such as `curl`, `ssh`,\n  `winget`, `certutil`, and Windows script hosts. Classroom software should be\n  inventoried and installed by IT into managed locations such as Program Files\n  before enabling enforcement on real student PCs.\n- Managed Chromium artifacts exist in the repository, but they should not be\n  treated as equivalent full-browser support for every deployment. Use Firefox\n  as the supported browser path unless the target environment has explicitly\n  validated a managed Chromium or Edge flow.\n\n## Privacy First, Not as a Feature, but as Architecture\n\nOpenPath was built from the ground up so that **student computers never share browsing data** with anyone. This is not a setting you can toggle; it is how the system works:\n\n| Promise                                   | How it's enforced                                                                                                                                                                                                          |\n| ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| **No telemetry**                          | The agents and browser extension send zero analytics or usage data to any third party. There are no tracking pixels, no beacons, no \"anonymous\" usage metrics.                                                             |\n| **No browsing history leaves the device** | The enforcement is local: DNS resolution and firewall rules run on the student's own machine. The central server knows the policy, not what each student tried to visit.                                                   |\n| **No data monetisation**                  | OpenPath is AGPL-3.0 licensed. There is no commercial entity harvesting data behind the scenes.                                                                                                                            |\n| **Local-only browser state**              | The browser extension keeps blocked-resource information in local runtime memory. It does not upload browsing activity.                                                                                                    |\n| **Native messaging stays on-machine**     | When the extension communicates with the system agent, that conversation never leaves localhost.                                                                                                                           |\n| **Auditable by design**                   | Every line of enforcement logic, agents, extension, and API, is in this repository under an open-source license. No hidden binaries, no obfuscated cloud rules. You can read exactly what runs on your students' machines. |\n\nYou can verify every one of these claims yourself: the entire codebase is here, in this repository. That is the point.\n\n\u003e **Read the full extension privacy policy:** [`firefox-extension/PRIVACY.md`](firefox-extension/PRIVACY.md)\n\n## How It Works\n\n```\n+-------------------------------------------------+\n|              OpenPath Server                    |\n|  +----------+  +-----------+  +--------------+  |\n|  | API      |  | Admin SPA |  | PostgreSQL   |  |\n|  | (tRPC)   |  | (React)   |  |              |  |\n|  +----+-----+  +-----------+  +--------------+  |\n|       |  Policy updates (SSE / scheduled)       |\n+-------+-----------------------------------------+\n        |\n        v\n+-----------------------+   +-----------------------+\n|  Linux Agent          |   |  Windows Agent         |\n|  dnsmasq + iptables   |   |  Acrylic DNS + FW      |\n|  local enforcement    |   |  local enforcement     |\n+-----------+-----------+   +-----------+-----------+\n            |                           |\n            v                           v\n     +-------------+             +-------------+\n     |  Browser    |             |  Browser    |\n     |  Extension  |             |  Extension  |\n     |  (local UI) |             |  (local UI) |\n     +-------------+             +-------------+\n```\n\n1. Each teacher defines approved domains for their classroom through the admin dashboard. IT sets up the infrastructure; teachers set the rules.\n2. Endpoint agents pull the policy and configure local DNS and firewall rules.\n3. The browser extension provides real-time visibility into what is blocked and lets users request unblocks.\n4. **All enforcement is local.** The server distributes policy; it does not inspect traffic.\n\n## What Ships Today\n\n| Package                                             | Purpose                                                                                |\n| --------------------------------------------------- | -------------------------------------------------------------------------------------- |\n| [`api/`](api/README.md)                             | Express + tRPC service, setup flow, agent delivery, and public request endpoints       |\n| [`react-spa/`](react-spa/README.md)                 | Administration UI for managing classrooms, domains, and policy                         |\n| [`linux/`](linux/README.md)                         | Debian/Ubuntu agent: dnsmasq, iptables, SSE updates, self-update                       |\n| [`windows/`](windows/README.md)                     | PowerShell agent: Acrylic DNS Proxy, Windows Firewall, scheduled tasks, browser policy |\n| [`firefox-extension/`](firefox-extension/README.md) | Browser extension with managed distribution for Firefox and Chromium                   |\n| [`shared/`](shared/README.md)                       | Shared schemas, domain helpers, validation, and role definitions                       |\n| [`dashboard/`](dashboard/README.md)                 | Compatibility layer bridging legacy REST flows to the tRPC API                         |\n\n## Getting Started\n\n### Prerequisites\n\n- Node.js \u003e= 20\n- PostgreSQL\n- npm workspaces\n\n### Quick start\n\n```bash\n# Clone and install\ngit clone https://github.com/balejosg/openpath.git\ncd openpath\nnpm install\nnpm run build --workspaces --if-present\n\n# Start the API and admin UI\nnpm run dev --workspace=@openpath/api\nnpm run dev --workspace=@openpath/react-spa\n```\n\nFor endpoint agents, see the platform-specific guides:\n\n- **Linux:** [`linux/README.md`](linux/README.md)\n- **Windows:** [`windows/README.md`](windows/README.md)\n\n### Evaluation resources\n\n| If you need...                    | Start here                                                                                     |\n| --------------------------------- | ---------------------------------------------------------------------------------------------- |\n| Self-hosting prerequisites        | [`docs/evaluation/self-hosted-prerequisites.md`](docs/evaluation/self-hosted-prerequisites.md) |\n| Deployment topologies             | [`docs/evaluation/deployment-shapes.md`](docs/evaluation/deployment-shapes.md)                 |\n| Adoption and ownership boundaries | [`docs/evaluation/adoption-path.md`](docs/evaluation/adoption-path.md)                         |\n| Architecture decisions            | [`docs/ADR.md`](docs/ADR.md)                                                                   |\n| Project roadmap                   | [`ROADMAP.md`](ROADMAP.md)                                                                     |\n| Security hardening                | [`docs/SECURITY-HARDENING.md`](docs/SECURITY-HARDENING.md)                                     |\n| Full documentation map            | [`docs/INDEX.md`](docs/INDEX.md)                                                               |\n\n## Help Us Fix This Problem\n\nDistractions in computer classrooms are a real, everyday problem for thousands of teachers. Commercial solutions are often expensive, privacy-invasive, or both. OpenPath exists because we believe there should be a transparent, auditable, privacy-respecting alternative, and **we need help building it**.\n\n### Ways to contribute\n\n- **Report bugs** - Found something broken? [Open an issue](https://github.com/balejosg/openpath/issues).\n- **Suggest features** - Have an idea that would help your classroom? Open a feature request or classroom feedback issue.\n- **Submit code** - Pick up an open issue, fix a bug, or improve a feature. See [`CONTRIBUTING.md`](CONTRIBUTING.md) for the workflow.\n- **Improve docs** - Clearer documentation helps more schools adopt the project.\n- **Test in your school** - Real-world feedback from teachers and IT teams is invaluable.\n- **Translate** - Help make OpenPath accessible to schools in your language.\n- **Spread the word** - Tell a colleague, write about it, or present it at your next tech meeting.\n\n### You don't need to be a developer\n\nIf you work in education and you understand the distraction problem, your perspective matters. Design feedback, workflow suggestions, and \"this doesn't make sense in a real classroom\" reports are just as valuable as pull requests.\n\nStart with [`ROADMAP.md`](ROADMAP.md) to see where help is useful now, and use\nthe GitHub issue templates to share classroom feedback, deployment blockers, or\nsmall contribution ideas.\n\n### Developer quick reference\n\n```bash\n# Verify your changes\nnpm run verify:quick          # Typecheck + lint + format\nnpm run verify:agent          # Agent-level checks\n\n# Run tests\nnpm run test:api\nnpm run test:react-spa\nnpm test --workspace=@openpath/firefox-extension\n```\n\nRead [`CONTRIBUTING.md`](CONTRIBUTING.md) for conventions, commit format, and PR workflow.\n\n## Trust, Security, and Auditing\n\n- **Security disclosure policy:** [`SECURITY.md`](SECURITY.md)\n- **Vulnerability reports:** Do not open public issues. Use a [GitHub private security advisory](https://github.com/balejosg/openpath/security/advisories) or contact the maintainers directly.\n- **Operator hardening checklist:** [`docs/SECURITY-HARDENING.md`](docs/SECURITY-HARDENING.md)\n- **Browser extension privacy posture:** [`firefox-extension/PRIVACY.md`](firefox-extension/PRIVACY.md)\n- **Public integration boundary:** [`docs/adr/0010-public-spa-extension-surface.md`](docs/adr/0010-public-spa-extension-surface.md)\n\n## License\n\nOpenPath is free software licensed under [`AGPL-3.0-or-later`](LICENSE).\n\nThis means you can use, study, modify, and redistribute it, as long as you share your changes under the same terms. If you run a modified version as a network service, the AGPL requires you to make the source available to its users.\n\nSee [`LICENSING.md`](LICENSING.md) for details.\n\n\u003e **Note:** Maintained documentation is English-only. The full documentation map lives in [`docs/INDEX.md`](docs/INDEX.md).\n\n---\n\n\u003cp align=\"center\"\u003e\n  \u003cem\u003eBuilt for classrooms that respect both focus and privacy.\u003c/em\u003e\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbalejosg%2Fopenpath","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbalejosg%2Fopenpath","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbalejosg%2Fopenpath/lists"}