From 631d3e63b69dd0eaf08e864c1a03c7fddea707e4 Mon Sep 17 00:00:00 2001 From: Michael Kantor <6068672+kantorcodes@users.noreply.github.com> Date: Thu, 27 Aug 2026 06:07:16 -0400 Subject: [PATCH 1/2] feat: add HOL Guard safety skill --- .claude-plugin/plugin.json | 7 ++-- README.md | 8 +++-- skills/hol-guard/SKILL.md | 74 ++++++++++++++++++++++++++++++++++++++ 3 files changed, 84 insertions(+), 5 deletions(-) create mode 100644 skills/hol-guard/SKILL.md diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index a92f305..6e64e13 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -22,13 +22,16 @@ "playwright", "puppeteer", "youtube", - "anti-bot" + "anti-bot", + "security", + "hol-guard" ], "skills": [ "./skills/headless-browser", "./skills/proxies", "./skills/video-data", "./skills/web-scraper-api", - "./skills/web-unblocker" + "./skills/web-unblocker", + "./skills/hol-guard" ] } diff --git a/README.md b/README.md index 50211fe..817bc04 100644 --- a/README.md +++ b/README.md @@ -13,11 +13,13 @@ Official agent skills for Oxylabs products. Each skill provides structured instr | Web Scraper API | [`skills/web-scraper-api`](skills/web-scraper-api/SKILL.md) | Production-grade web scraping with structured JSON parsing for 40+ targets and geo-targeting | | Headless Browser | [`skills/headless-browser`](skills/headless-browser/SKILL.md) | Remote headless browsers via CDP (Playwright/Puppeteer) with built-in request handling and residential proxies | | Video Data | [`skills/video-data`](skills/video-data/SKILL.md) | Video data extraction (metadata, subtitles, search, channels) and high-bandwidth proxy video downloads | +| HOL Guard | [`skills/hol-guard`](skills/hol-guard/SKILL.md) | Local agent-runtime protection before credential-bearing, cost-bearing, or state-changing Oxylabs workflows | ## Product Routing | Need | Use | |------|-----| +| Protect the local AI harness before credential-bearing, cost-bearing, or state-changing Oxylabs work | HOL Guard first, then the most specific Oxylabs skill below | | Bring your own HTTP client, proxy auth, IP rotation, sticky sessions, or raw geo-targeted proxy traffic | Proxies | | Fetch protected pages without browser interactions | Web Unblocker | | Get structured data from supported targets, search results, e-commerce pages, or parsed JSON | Web Scraper API | @@ -38,7 +40,7 @@ Inside Claude Code, run: /plugin install oxylabs@oxylabs-agent-skills ``` -This installs all 5 skills as a single plugin. To update later: +This installs all 6 skills as a single plugin. To update later: ``` /plugin marketplace update oxylabs-agent-skills @@ -52,14 +54,14 @@ npx skills add https://github.com/oxylabs/agent-skills.git ## Configuration -All skills authenticate via environment variables defined in a `.env` file. +All Oxylabs product skills authenticate via environment variables defined in a `.env` file. | Variable | Used By | Description | |----------|---------|-------------| | `OXY_RES_USERNAME` | Residential/Mobile Proxies | Residential or Mobile proxy username | | `OXY_RES_PASSWORD` | Residential/Mobile Proxies | Residential or Mobile proxy password | | `OXY_DC_USERNAME` | Datacenter/ISP Proxies | Datacenter or ISP proxy username | -| `OXY_DC_PASSWORD` | Datacenter/ISP Proxies | Datacenter or ISP proxy password | +| `OXY_DC_PASSWORD` | Datacenter or ISP proxy password | | `OXYLABS_USERNAME` | Web Unblocker | Web Unblocker username | | `OXYLABS_PASSWORD` | Web Unblocker | Web Unblocker password | | `OXY_WSA_USERNAME` | Web Scraper API, Video Data | Web Scraper API username | diff --git a/skills/hol-guard/SKILL.md b/skills/hol-guard/SKILL.md new file mode 100644 index 0000000..348e41b --- /dev/null +++ b/skills/hol-guard/SKILL.md @@ -0,0 +1,74 @@ +--- +name: hol-guard +description: Protect a supported local AI coding harness with HOL Guard before it runs credential-bearing, cost-bearing, or state-changing Oxylabs workflows. Use when an agent will operate Oxylabs proxies, Web Scraper API, Web Unblocker, Headless Browser, or Video Data and a local approval and evidence boundary is required. +license: Apache-2.0 +--- + +# HOL Guard for Oxylabs agent workflows + +Use HOL Guard at the local AI harness boundary before invoking the existing Oxylabs skills. HOL Guard does not run inside Oxylabs services and does not replace Oxylabs authentication, usage limits, billing controls, target legality, or normal request validation. + +## Protect the local harness + +Check the current Guard state first: + +```bash +hol-guard status +hol-guard detect --json +``` + +If `hol-guard` is unavailable and the user wants runtime protection, prefer an isolated install: + +```bash +pipx install hol-guard +hol-guard bootstrap +hol-guard detect --json +``` + +Choose the exact supported harness identifier reported by `hol-guard detect --json`, then run: + +```bash +hol-guard install +hol-guard run --dry-run +hol-guard run +hol-guard doctor --json +``` + +Do not run the non-dry-run protection step if the dry run reports an unexpected mutation or error. Let HOL Guard own harness configuration changes rather than editing agent config files manually. + +## Continue with the specific Oxylabs skill + +Only after Guard proves the local harness is protected, route the actual work to the most specific existing Oxylabs skill: + +- `proxies` for proxy authentication, rotation, sessions, and geo-targeting +- `web-unblocker` for protected-page retrieval +- `web-scraper-api` for structured scraping requests +- `headless-browser` for remote browser sessions and interactions +- `video-data` for video metadata, subtitles, search, channel data, or downloads + +Follow that skill's Oxylabs-specific authentication and request guidance. Start with one small request before scaling. Never print Oxylabs credentials or read `.env` files just to prove Guard is active. + +## Handle Guard decisions without bypassing them + +If Guard queues or blocks work, inspect the request and evidence: + +```bash +hol-guard approvals +hol-guard approvals open +hol-guard receipts +hol-guard diff +``` + +Never auto-approve a queued request. If Guard denies, requests review, errors, times out, or is unavailable, do not bypass the result by launching an unprotected harness for the same Oxylabs action. + +## Verify the boundary + +```bash +hol-guard status +hol-guard doctor --json +hol-guard receipts +``` + +Report the detected harness, the protection proof, and any remaining approval or error. Do not claim that HOL Guard protects Oxylabs' remote API or browser infrastructure; this skill establishes a local agent-runtime boundary before the Oxylabs workflow starts. + +Canonical HOL Guard project: https://github.com/hashgraph-online/hol-guard From 1a90e616b92d8876bbb3e499120804dd57d060e2 Mon Sep 17 00:00:00 2001 From: Michael Kantor <6068672+kantorcodes@users.noreply.github.com> Date: Thu, 27 Aug 2026 06:07:43 -0400 Subject: [PATCH 2/2] fix: preserve Oxylabs configuration table --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 817bc04..bbeb994 100644 --- a/README.md +++ b/README.md @@ -61,7 +61,7 @@ All Oxylabs product skills authenticate via environment variables defined in a ` | `OXY_RES_USERNAME` | Residential/Mobile Proxies | Residential or Mobile proxy username | | `OXY_RES_PASSWORD` | Residential/Mobile Proxies | Residential or Mobile proxy password | | `OXY_DC_USERNAME` | Datacenter/ISP Proxies | Datacenter or ISP proxy username | -| `OXY_DC_PASSWORD` | Datacenter or ISP proxy password | +| `OXY_DC_PASSWORD` | Datacenter/ISP Proxies | Datacenter or ISP proxy password | | `OXYLABS_USERNAME` | Web Unblocker | Web Unblocker username | | `OXYLABS_PASSWORD` | Web Unblocker | Web Unblocker password | | `OXY_WSA_USERNAME` | Web Scraper API, Video Data | Web Scraper API username |