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..bbeb994 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,7 +54,7 @@ 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 | |----------|---------|-------------| 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