Skip to content
Back to search

geoready

GEO Optimizer plugins from Auriti Labs

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/Auriti-Labs/geo-optimizer-skill with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/Auriti-Labs/geo-optimizer-skill'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/auriti-labs--geo-optimizer-skill/badge.svg)](/listings/auriti-labs--geo-optimizer-skill)

HTML

<a href="/listings/auriti-labs--geo-optimizer-skill"><img src="/api/listings/auriti-labs--geo-optimizer-skill/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

# Zero install
uvx --from geo-optimizer-skill geo audit --url https://yoursite.com

# Or install it
pip install -U geo-optimizer-skill

geo audit --url https://yoursite.com                   # score 0–100 + prioritized fixes
geo fix --url https://yoursite.com                     # preview robots.txt, llms.txt, schema, meta (--apply to write)
geo audit --url https://yoursite.com --threshold 70    # exit 1 below 70 — use it as a CI gate
geo citations --brand "Acme" --domain acme.com         # does AI cite you? (bring your own API key)

<details> <summary><b>All 16 commands</b></summary>

# Audit a full sitemap and surface the weakest pages first
geo audit --sitemap https://yoursite.com/sitemap.xml --max-urls 25

# Compare before/after versions of a page
geo diff --before https://yoursite.com/page-old --after https://yoursite.com/page-new

# Save history, detect regressions, and show the trend
geo audit --url https://yoursite.com --save-history --regression
geo history --url https://yoursite.com

# What changed since the last snapshot? (CI: --fail-on warning)
geo drift --url https://yoursite.com

# Passive AI visibility snapshot for a domain
geo monitor --domain yoursite.com

# Ask real AI engines whether your brand is mentioned and your domain cited.
# AI answers vary run to run — sample each query 5x for a confidence interval.
geo citations --brand "YourBrand" --domain yoursite.com --topic "your product category" --runs 5

# Save or query archived AI answer snapshots, and score citation quality in one
geo snapshots --query "best GEO tool" --from 2026-03-01 --to 2026-03-30
geo snapshots --quality --snapshot-id 12 --target-domain yoursite.com

# Recurring monitoring with an HTML trend report
geo track --url https://yoursite.com --report --output ./geo-track-report.html

# Generate llms.txt from the sitemap, or check an existing one for stale URLs (exit 1)
geo llms --base-url https://yoursite.com --output ./public/llms.txt
geo llms --base-url https://yoursite.com --check-drift

# Generate or analyze JSON-LD schema
geo schema --type website --name "Your Site" --url https://yoursite.com
geo schema --file index.html --analyze

# Site-level and diagnostic tools
geo coherence --sitemap https://yoursite.com/sitemap.xml   # cross-page terminology consistency
geo authority --sitemap https://yoursite.com/sitemap.xml   # topical authority: clusters, pillars, depth
geo logs --file access.log                                  # AI crawler activity from server logs
geo access --url https://yoursite.com                       # browser vs AI-bot access simulation
geo perception --url https://yoursite.com                   # what an AI would extract from the page

Guides for most commands live in [`docs/`](docs/). Provider setup for `geo citations` (Perplexity, OpenAI, Anthropic, Groq, Gemini, MiniMax, DeepSeek, and SerpBase for the real Google SERP + AI Overview): [docs/llm-providers.md](docs/llm-providers.md).

</details>

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 15 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. {
  2. "name": "geoready",
  3. "description": "GEO Optimizer plugins from Auriti Labs",
  4. "owner": {
  5. "name": "Auriti Labs",
  6. "url": "https://geoready.dev"
  7. },
  8. "plugins": [
  9. {
  10. "name": "geo-optimizer",
  11. "source": "./plugins/geo-optimizer",
  12. "description": "GEO audit skill plus the geo-mcp server (12 tools): score a site 0-100 for AI search visibility and generate the fixes."
  13. }
  14. ]
  15. }
README.md · README · 522 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <div align="center">
  2. <img src="assets/geoready-logo.svg" alt="GeoReady GEO Optimizer — Answer Engine Optimization toolkit" width="560"/>
  3. # Your site ranks on Google. Does ChatGPT cite it?
  4. ### The open-source **Answer Engine Optimization (AEO)** & **Generative Engine Optimization (GEO)** toolkit.
  5. **GEO Optimizer** is the open-source engine behind **[GeoReady](https://geoready.dev/?utm_source=github&utm_medium=readme&utm_campaign=entity)**, the hosted AI visibility audit at geoready.dev. Run it here from the terminal, or in the browser on geoready.dev.
  6. One command scores any website 0–100 on whether **ChatGPT, Perplexity, Gemini, Claude, and Google AI Overviews** can crawl it, understand it, and cite it — then tells you exactly what to fix.
  7. [![PyPI](https://img.shields.io/pypi/v/geo-optimizer-skill?style=flat-square&color=3b82f6)](https://pypi.org/project/geo-optimizer-skill/)
  8. [![Downloads/month](https://static.pepy.tech/badge/geo-optimizer-skill/month)](https://pepy.tech/project/geo-optimizer-skill)
  9. [![GitHub Stars](https://badgen.net/github/stars/auriti-labs/geo-optimizer-skill?icon=github&color=yellow&label=stars)](https://github.com/auriti-labs/geo-optimizer-skill/stargazers)
  10. [![CI](https://github.com/auriti-labs/geo-optimizer-skill/actions/workflows/ci.yml/badge.svg)](https://github.com/auriti-labs/geo-optimizer-skill/actions)
  11. [![Python 3.10+](https://img.shields.io/badge/python-3.10+-3776ab?style=flat-square&logo=python&logoColor=white)](https://python.org)
  12. [![License: MIT](https://img.shields.io/badge/license-MIT-22c55e?style=flat-square)](LICENSE)
  13. ```bash
  14. uvx --from geo-optimizer-skill geo audit --url https://yoursite.com
  15. ```
  16. *No install, no account, no API key. Runs in seconds.*
  17. **No terminal?** Paste your URL into the browser version instead. Same engine, free, no account:
  18. [![Run the free web audit](https://img.shields.io/badge/Run_the_free_web_audit-geoready.dev-0D9488?style=for-the-badge)](https://geoready.dev/?utm_source=github&utm_medium=readme&utm_campaign=hero)
  19. [![The free web audit on geoready.dev: paste a URL, get a 0–100 GEO score, nine category results and the free fixes. Live run on geoready.dev, 17 October 2026: 94/100, Excellent.](assets/web-audit.gif)](https://geoready.dev/?utm_source=github&utm_medium=readme&utm_campaign=hero-gif)
  20. *The browser audit on geoready.dev: paste a URL, read the score, the nine category results and the free fixes. Live run on geoready.dev itself, 17 October 2026.*
  21. <img src="assets/tui-audit.svg" alt="geo audit terminal dashboard on geoready.dev: 94/100 Excellent, nine rubric v2 categories with per-category scores, extra checks and top fixes" width="800"/>
  22. [Quick Start](#quick-start) · [Free web audit, no account](https://geoready.dev/?utm_source=github&utm_medium=readme&utm_campaign=nav) · [Docs](https://geoready.dev/docs/) · [The book](#the-book-behind-the-engine-ai-search-engineering) · [Changelog](CHANGELOG.md)
  23. </div>
  24. ---
  25. ## What is GEO Optimizer?
  26. **GEO Optimizer audits how ready a website is for AI answer engines** — ChatGPT, Perplexity, Google AI Overviews, Gemini, and Claude: crawler access, structured data, content and discovery signals. It scores the site 0–100 and generates the fixes. It does not observe what those engines say about you. It is free, MIT-licensed, and runs as a CLI, a Python library, an [MCP server](#mcp-server), a [GitHub Action](#cicd--fail-the-build-when-ai-readiness-drops), or an [Astro integration](#astro-integration).
  27. *Also called GEO, AI SEO, or LLM SEO — same problem: an answer engine gives one response and cites a handful of sources. Ranking on Google does not make you one of them. Being reachable, parseable and quotable are conditions for being cited, not a promise of it.*
  28. **16 CLI commands** · **9 scoring categories** · **27 AI crawlers checked** · **47 content checks** · **12 MCP tools** · **8 output formats** · **2,000+ tests**
  29. ### What a real audit looks like
  30. Two runs of `geo audit`, September 2026. `example.com` has no robots.txt, no `llms.txt`, and no structured data. `geoready.dev` is built with this engine's own [Astro integration](#astro-integration). Excerpts, condensed from the full text output.
  31. <table>
  32. <tr><th>example.com</th><th>geoready.dev</th></tr>
  33. <tr><td>
  34. ```
  35. [█░░░░░░░░░░░░░░░░░░░] 8/100
  36. ❌ CRITICAL — Core signals for AI
  37. search are missing
  38. 📋 PRIORITY NEXT STEPS:
  39. 1. Create robots.txt with Allow rules
  40. for AI bots (GPTBot, ClaudeBot,
  41. PerplexityBot)
  42. 2. Create /llms.txt for AI indexing
  43. 3. Add WebSite JSON-LD schema
  44. 4. Add Organization JSON-LD schema
  45. 5. Add FAQPage schema with site FAQs
  46. ```
  47. </td><td>
  48. ```
  49. [██████████████████░░] 91/100
  50. 🏆 EXCELLENT
  51. ✅ 27/27 AI crawlers allowed
  52. ✅ llms.txt found (~3554 words)
  53. ✅ 7 schema types
  54. ✅ 0 prompt-injection patterns
  55. ✅ 1/4 Knowledge Graph pillars
  56. ⚠️ No dateModified signal
  57. (Wikipedia, Wikidata, LinkedIn,
  58. Crunchbase)
  59. ```
  60. </td></tr>
  61. </table>
  62. Across 1,800+ sites audited through [GeoReady](https://geoready.dev/state-of-geo/?utm_source=github&utm_medium=readme&utm_campaign=benchmark) (latest audit per domain, as of 17 October 2026), the median score is **59/100**, 58% publish an `llms.txt` and 76% ship JSON-LD structured data. 58% of them land in the Foundation band (36–67), 28% in Good, 12% in Critical and 2% in Excellent. Scores mix rubric v1 (engine 4.13 to 4.18) and v2 (4.19). The sample is self-selected (people who chose to audit their site), so treat it as directional, not a census of the web.
  63. <img src="assets/benchmark.svg" alt="Chart of 1,800+ audited sites: median GEO score 59 out of 100, average 56.5, 58% publish an llms.txt file, 76% ship JSON-LD structured data. Self-selected sample, 17 October 2026." width="800"/>
  64. <img src="assets/benchmark-bands.svg" alt="Chart of how 1,896 audited sites split across the GEO score bands: Foundation 57.6%, Good 28.2%, Critical 12.4%, Excellent 1.8%. Latest audit per domain, 17 October 2026; self-selected sample." width="800"/>
  65. **Where does your site land?** [Run the free audit](https://geoready.dev/?utm_source=github&utm_medium=readme&utm_campaign=benchmark-chart) and compare your score with the median, or run `geo audit` above.
  66. ### Then it writes the fixes
  67. `geo fix` turns the audit into files: robots.txt rules for all 27 AI bots, `llms.txt`, JSON-LD schema, AI discovery endpoints, and meta tags. It previews by default and writes only with `--apply`. The score after fixes is the tool's own estimate, not a measured result.
  68. <img src="assets/fix.svg" alt="geo fix on example.com: 9 fixes planned, estimated score 22/100 to 64/100" width="800"/>
  69. Prefer no terminal? Run the same audit free at [geoready.dev](https://geoready.dev/?utm_source=github&utm_medium=readme&utm_campaign=proof-table) — no account needed.
  70. ---
  71. ## Quick Start
  72. ```bash
  73. # Zero install
  74. uvx --from geo-optimizer-skill geo audit --url https://yoursite.com
  75. # Or install it
  76. pip install -U geo-optimizer-skill
  77. geo audit --url https://yoursite.com # score 0–100 + prioritized fixes
  78. geo fix --url https://yoursite.com # preview robots.txt, llms.txt, schema, meta (--apply to write)
  79. geo audit --url https://yoursite.com --threshold 70 # exit 1 below 70 — use it as a CI gate
  80. geo citations --brand "Acme" --domain acme.com # does AI cite you? (bring your own API key)
  81. ```
  82. <details>
  83. <summary><b>All 16 commands</b></summary>
  84. ```bash
  85. # Audit a full sitemap and surface the weakest pages first
  86. geo audit --sitemap https://yoursite.com/sitemap.xml --max-urls 25
  87. # Compare before/after versions of a page
  88. geo diff --before https://yoursite.com/page-old --after https://yoursite.com/page-new
  89. # Save history, detect regressions, and show the trend
  90. geo audit --url https://yoursite.com --save-history --regression
  91. geo history --url https://yoursite.com
  92. # What changed since the last snapshot? (CI: --fail-on warning)
  93. geo drift --url https://yoursite.com
  94. # Passive AI visibility snapshot for a domain
  95. geo monitor --domain yoursite.com
  96. # Ask real AI engines whether your brand is mentioned and your domain cited.
  97. # AI answers vary run to run — sample each query 5x for a confidence interval.
  98. geo citations --brand "YourBrand" --domain yoursite.com --topic "your product category" --runs 5
  99. # Save or query archived AI answer snapshots, and score citation quality in one
  100. geo snapshots --query "best GEO tool" --from 2026-03-01 --to 2026-03-30
  101. geo snapshots --quality --snapshot-id 12 --target-domain yoursite.com
  102. # Recurring monitoring with an HTML trend report
  103. geo track --url https://yoursite.com --report --output ./geo-track-report.html
  104. # Generate llms.txt from the sitemap, or check an existing one for stale URLs (exit 1)
  105. geo llms --base-url https://yoursite.com --output ./public/llms.txt
  106. geo llms --base-url https://yoursite.com --check-drift
  107. # Generate or analyze JSON-LD schema
  108. geo schema --type website --name "Your Site" --url https://yoursite.com
  109. geo schema --file index.html --analyze
  110. # Site-level and diagnostic tools
  111. geo coherence --sitemap https://yoursite.com/sitemap.xml # cross-page terminology consistency
  112. geo authority --sitemap https://yoursite.com/sitemap.xml # topical authority: clusters, pillars, depth
  113. geo logs --file access.log # AI crawler activity from server logs
  114. geo access --url https://yoursite.com # browser vs AI-bot access simulation
  115. geo perception --url https://yoursite.com # what an AI would extract from the page
  116. ```
  117. Guides for most commands live in [`docs/`](docs/). Provider setup for `geo citations` (Perplexity, OpenAI, Anthropic, Groq, Gemini, MiniMax, DeepSeek, and SerpBase for the real Google SERP + AI Overview): [docs/llm-providers.md](docs/llm-providers.md).
  118. </details>
  119. ---
  120. ## After the one-shot audit
  121. `geo audit` is a snapshot. It can't tell you that your score dropped after last Tuesday's deploy, or whether citations started appearing once your fixes shipped. `geo history`, `geo drift`, and `geo track` help — but only when someone remembers to run them.
  122. The hosted platform runs the same engine on a schedule, so the watching happens without you:
  123. - **Free plan** — audits, your last 5 reports, and one real AI answer check a week (Perplexity).
  124. - **Pro / Agency, from $19/mo** — weekly score monitoring, regression alerts, multi-site portfolios, client reporting. [Pricing](https://geoready.dev/pricing/?utm_source=github&utm_medium=readme&utm_campaign=bridge).
  125. [**Create a free account**](https://app.geoready.dev/signup/?utm_source=github&utm_medium=readme&utm_campaign=bridge) · [Free web audit, no account](https://geoready.dev/?utm_source=github&utm_medium=readme&utm_campaign=bridge) · [Get the free 160-page GEO Readiness Manual](https://geoready.dev/geo-readiness-manual/?utm_source=github&utm_medium=readme&utm_campaign=bridge)
  126. Same engine everywhere: the platform adds what a local CLI cannot — server-side monitoring, history, and team features.
  127. <details>
  128. <summary><b>Open source vs hosted — the full comparison</b></summary>
  129. | | GEO Optimizer (this repo) | [geoready.dev](https://geoready.dev) Free | GeoReady Pro / Agency |
  130. |---|---|---|---|
  131. | **Access** | MIT, runs locally | Web audit, no account | [Self-serve sign-up](https://app.geoready.dev/signup/?utm_source=github&utm_medium=readme&utm_campaign=comparison) |
  132. | **Best for** | Developers, CI/CD, automation | Quick checks, SEO specialists | Ongoing clients, multi-site portfolios |
  133. | **What you get** | Full engine, JSON output, all 16 commands | Single-URL score, [free tools](https://geoready.dev/tools/llms-txt-generator/) | Monitoring, score history, regression alerts, agency reporting |
  134. | **Price** | Free forever | Free forever | From $19/month — [pricing](https://geoready.dev/pricing/) |
  135. </details>
  136. ---
  137. ## Is AI citing you? Ask it directly.
  138. `geo citations` sends the questions your customers ask to real answer engines, then reports whether your brand is mentioned, whether your domain is cited as a source, and which competitors are cited instead.
  139. <img src="assets/citations.gif" alt="geo citations demo — is your brand cited by ChatGPT and Perplexity?" width="800"/>
  140. Two honest caveats, both built into the tool:
  141. - **Answers are not deterministic.** The same question can cite different sources on each run. `--runs 5` samples every query five times and reports a confidence interval instead of a single yes/no.
  142. - **Not every API shows sources.** Perplexity Sonar returns the real source URLs. OpenAI, Anthropic, and Groq only reveal what the model already knows about your brand. Google AI Overviews is a SERP feature, not a model, so `--provider serpbase` observes the real Google results page instead.
  143. ---
  144. ## What it checks
  145. | Area | Points | What GEO Optimizer looks for |
  146. |------|--------|------------------------------|
  147. | **Google AI readiness** | /20 | Indexing, snippets, canonical, dates, byline, links, viewport, sitemap, and manual generative-AI control |
  148. | **Robots.txt** | /14 | Googlebot and citation-bot access; found 3 + citation bots allowed 11 |
  149. | **Schema JSON-LD** | /14 | Validity, richness, FAQ, Article, Organization, WebSite, and visible name match |
  150. | **Content** | /14 | H1, statistics, links, word count, heading hierarchy, lists/tables, front-loading, image alt coverage |
  151. | **Brand & Entity** | /12 | Brand coherence, Knowledge Graph, about/contact, geo identity, topic authority |
  152. | **Meta Tags** | /11 | Title, description, and Open Graph; canonical is scored by G-CANONICAL |
  153. | **llms.txt** | /6 | Found, sections, links, and llms-full.txt; useful to other AI agents, ignored by Google Search |
  154. | **Signals** | /6 | `<html lang>`, RSS/Atom feed, valid freshness |
  155. | **AI Discovery** | /3 | `ai.txt`, `summary.json`, and markdown negotiation |
  156. **Score bands:** 86–100 Excellent · 68–85 Good · 36–67 Foundation · 0–35 Critical. Rubric v2 is the default; use `geo audit --score-version 1` for legacy v1 comparisons, `--score-version 3` for the opt-in rubric that scores a missing robots.txt as full access, and `--score-version 4` for v3 plus schema points that apply by page type. Every weight is in [`models/config.py`](src/geo_optimizer/models/config.py). Full rubric: [docs/scoring-rubric.md](docs/scoring-rubric.md).
  157. <details>
  158. <summary><b>Beyond the score: 10 more checks</b></summary>
  159. **Negative Signals** can deduct up to 5 points. The other checks are informational and do not change the score.
  160. | Check | What it detects |
  161. |-------|-----------------|
  162. | **Negative Signals** | 8 anti-citation signals: CTA overload, popups, thin content, keyword stuffing, missing author, boilerplate ratio |
  163. | **CDN Crawler Access** | Does Cloudflare/Akamai/Vercel block GPTBot, ClaudeBot, PerplexityBot? |
  164. | **JS Rendering** | Is content accessible without JavaScript? SPA framework detection |
  165. | **Prompt Injection Detection** | 8 manipulation patterns: hidden text, invisible Unicode, LLM instructions, HTML comment injection, monochrome text, micro-font, data-attr injection, aria-hidden abuse |
  166. | **Trust Stack Score** | 5-layer trust aggregation (Technical, Identity, Social, Academic, Consistency) — grade A–F |
  167. | **RAG Chunk Readiness** | Section word counts, definition openings, heading boundaries, anchor sentences |
  168. | **Content Decay Prediction** | Temporal, statistical, version, event, and price decay patterns — evergreen score 0–100 |
  169. | **Platform Citation Profile** | Per-platform readiness scores for ChatGPT, Perplexity, Google AI |
  170. | **Multimodal Readiness** | Alt coverage, captions, VideoObject/AudioObject schema, subtitle tracks, transcripts |
  171. | **WebMCP Readiness** | Chrome WebMCP support: `registerTool()`, `toolname` attributes, `potentialAction` schema |
  172. Plus a separate **Citability Score** (0–100) built from 47 content checks, 9 of them taken directly from the methods tested in the [KDD 2024 GEO paper](https://arxiv.org/abs/2311.09735). Method list: [docs/geo-methods.md](docs/geo-methods.md).
  173. </details>
  174. **Topic authority** — answer engines map entities across a site, not single pages. `geo authority` clusters your pages by topic and scores depth, interlinking, and pillar pages:
  175. <img src="assets/authority.gif" alt="geo authority demo — site-level topical authority score and recommendations" width="800"/>
  176. ---
  177. ## Show your GEO score
  178. A live badge for your README — like a coverage badge, for AI visibility:
  179. ![GEO Score](https://geoready.dev/badge?url=https://geoready.dev)
  180. ```markdown
  181. [![GEO Score](https://geoready.dev/badge?url=https://yoursite.com)](https://geoready.dev?utm_source=badge)
  182. ```
  183. Re-audited and cached hourly. No account needed. Colors: 86–100 green · 68–85 cyan · 36–67 yellow · 0–35 red.
  184. ---
  185. ## Integrations
  186. ### CI/CD — fail the build when AI-readiness drops
  187. Treat AI visibility like test coverage. The GitHub Action scores your site, fails the build below a threshold, and uploads findings to the Security tab:
  188. ```yaml
  189. # .github/workflows/geo.yml
  190. - uses: Auriti-Labs/geo-optimizer-skill@v4.23.0
  191. with:
  192. url: https://yoursite.com
  193. min-score: 70 # fail the build below 70
  194. format: sarif # findings in the GitHub Security tab
  195. ```
  196. Any CI that runs Python works (GitLab, Jenkins, CircleCI). For longitudinal checks: `geo drift --url … --fail-on warning`. Output formats: `text`, `json`, `rich`, `html`, `pdf`, `sarif`, `junit`, `github`. The JSON format is the stable integration contract — see [docs/json-contract.md](docs/json-contract.md).
  197. `--format html` writes a self-contained report you can hand to a client. This one is the real report for geoready.dev:
  198. <img src="assets/html-report.png" alt="GEO Optimizer HTML report for geoready.dev — score 91/100, per-category results, and recommendations" width="560"/>
  199. ### MCP Server
  200. Use GEO Optimizer from Claude, Cursor, Windsurf, or any MCP client:
  201. ```bash
  202. pip install "geo-optimizer-skill[mcp]"
  203. claude mcp add geo-optimizer -- geo-mcp
  204. ```
  205. Then ask: *"audit my site and fix what's missing."*
  206. #### What runs where
  207. | Where | What it does | What it needs |
  208. |-------|--------------|---------------|
  209. | MCP server (`geo-mcp`) | Audits, content citability, crawler access, schema, comparison and fixes. It does not query answer engines, so it cannot tell you whether a live answer cites you. | Nothing beyond the install |
  210. | CLI `geo citations` | Sends questions to answer engines and reports mentions and cited sources. | Your own provider API key; the provider bills you |
  211. | [GeoReady](https://geoready.dev) (hosted service, separate from this package) | Scheduled monitoring, score history, alerts and several domains in one account. | An account |
  212. #### Claude Code plugin
  213. Installs the skill and the MCP server in one go, no files to copy:
  214. ```text
  215. /plugin marketplace add Auriti-Labs/geo-optimizer-skill
  216. /plugin install geo-optimizer@geoready
  217. ```
  218. On Claude Code 2.1.275 or later one step is enough: `/plugin install geo-optimizer --marketplace Auriti-Labs/geo-optimizer-skill` (the shell form, `claude plugin install ...`, needs 2.1.292). The plugin starts `geo-mcp` with `uvx`, so [uv](https://docs.astral.sh/uv/) must be on your `PATH`. It does not install the `geo` CLI the skill runs: the skill's preflight asks for it.
  219. <details>
  220. <summary><b>12 MCP tools</b></summary>
  221. | Tool | Purpose |
  222. |------|---------|
  223. | `geo_audit` | Full audit with score + recommendations |
  224. | `geo_fix` | Generate fix files |
  225. | `geo_llms_generate` | Generate llms.txt |
  226. | `geo_citability` | Content citability analysis (47 checks) |
  227. | `geo_schema_validate` | Validate JSON-LD |
  228. | `geo_compare` | Compare multiple sites |
  229. | `geo_gap_analysis` | Explain the gap between two sites and prioritize fixes |
  230. | `geo_ai_discovery` | Check AI discovery endpoints |
  231. | `geo_check_bots` | Check bot access via robots.txt |
  232. | `geo_trust_score` | 5-layer trust signal aggregation |
  233. | `geo_negative_signals` | 8 anti-citation signal detection |
  234. | `geo_factual_accuracy` | Audit unsourced claims, contradictions, and broken citations |
  235. </details>
  236. ### Python API
  237. ```python
  238. from geo_optimizer import audit # or audit_async
  239. result = audit("https://example.com")
  240. result.score # int, 0–100
  241. result.band # "critical" | "foundation" | "good" | "excellent"
  242. result.citability.total_score # int, 0–100
  243. result.score_breakdown # {"robots": ..., "llms": ..., ...}
  244. result.recommendations # list of prioritized fixes
  245. ```
  246. ### Astro Integration
  247. Generates `llms.txt`, `/.well-known/ai.txt`, and `/ai/summary.json` from your built routes at build time, and never overwrites hand-curated files. geoready.dev builds with it. Not yet published to npm — copy [`integrations/astro-geoready/`](integrations/astro-geoready/) to `integrations/astro-geoready/` in your project root:
  248. ```js
  249. // astro.config.mjs
  250. import geoReady from './integrations/astro-geoready/index.mjs';
  251. export default defineConfig({
  252. site: 'https://yoursite.com',
  253. integrations: [geoReady({ siteName: 'Your Site' })],
  254. });
  255. ```
  256. ### More
  257. - **AI context files** — load GEO expertise into Claude Projects, ChatGPT, Cursor, Windsurf, or Kiro from [`ai-context/`](ai-context/).
  258. - **Plugins** — add custom checks through the `geo_optimizer.checks` entry point. Example: [`examples/example_plugin.py`](examples/example_plugin.py).
  259. ---
  260. ## Research foundation
  261. | Paper | Venue | What it found |
  262. |-------|-------|---------------|
  263. | [GEO: Generative Engine Optimization](https://arxiv.org/abs/2311.09735) | **KDD 2024** | 9 methods, evaluated on GEO-bench (10,000 queries). The best (citing sources, adding quotations, adding statistics) raised source visibility by up to 40%. Gains were largest for lower-ranked sources. |
  264. | [AutoGEO](https://arxiv.org/abs/2510.11438) | arXiv preprint (2025) | Rules extracted automatically from engine preferences: on average about 36% over the strongest KDD method (about 21% for the smaller AutoGEO-Mini). |
  265. | [C-SEO Bench](https://arxiv.org/abs/2506.11097) | **NeurIPS D&B 2025** | Most content-rewriting tricks do not work. Ranking the source matters more than rewriting it. |
  266. That finding is consistent with how the tool is weighted: GEO Optimizer puts most of its weight on whether crawlers can reach and parse a page (robots.txt, `llms.txt`, schema, meta) and treats content rewriting as the smaller lever. It measures readiness signals; it cannot guarantee that any engine will cite you, and it says so.
  267. The full reasoning behind each signal and weight is written up in the book below.
  268. ---
  269. ## The book behind the engine: *AI Search Engineering*
  270. **AI Search Engineering — A Technical Guide to Generative Engine Optimization (GEO), AI Citations, and Agent-Ready Websites**
  271. Juan Camilo Auriti · 992 pages · English · 10 September 2026 · ISBN 979-8172934568
  272. **The book explains the reasoning; this engine runs it.** The scoring weights, the eight signal categories, and the evidence classification described in print are rubric v1, still implemented in this repository and available with `--score-version 1`. Rubric v2, the default, adds a Google AI readiness category built on Google's own documentation.
  273. It treats GEO as an engineering discipline rather than a collection of tricks, organized around the path a page travels before it can be cited. Each stage maps to something you can run here:
  274. | # | Stage in the book | Where the engine checks it |
  275. |---|-------------------|----------------------------|
  276. | 1 | Discovery | `llms.txt`, sitemap audit, AI discovery endpoints |
  277. | 2 | Crawling | robots.txt (27 bots), CDN access, `geo access`, `geo logs` |
  278. | 3 | Machine understanding | JSON-LD schema, JS rendering, entity signals, `geo perception` |
  279. | 4 | Retrieval | RAG chunk readiness, `geo authority` |
  280. | 5 | Answer generation | Citability score (47 checks) |
  281. | 6 | Citation | `geo citations`, `geo snapshots`, `geo track` |
  282. | 7 | Interaction | `/ai/*.json` endpoints, `.well-known/ai.txt` |
  283. | 8 | Action | WebMCP readiness, prompt-injection detection |
  284. It covers how answer engines discover and use web content — keeping documented behaviour separate from research findings and inference — auditing crawler access, rendering, and entity signals, engineering content for extraction without "AI-friendly" formulas, and operational GEO workflows for teams and agencies. It is written for developers, technical SEOs, consultants, agencies, product teams, and site owners who want to know what can actually be measured, implemented, and defended in AI search — no guarantees, no invented ranking factors, no hype presented as fact. Full stage-by-stage map of the book against the engine:
  285. [**Paperback on Amazon**](https://www.amazon.it/dp/B0HJGLW5NP) · [**Kindle edition**](https://www.amazon.it/dp/B0H8K319JM) · [Book page](https://geoready.dev/book/) · [Free 160-page GEO Readiness Manual](https://geoready.dev/geo-readiness-manual/?utm_source=github&utm_medium=readme&utm_campaign=book)
  286. ---
  287. ## Related tools
  288. GEO Optimizer scores **input-side readiness** — the signals that make a site reachable, parseable, and citable. Outside the lightweight `geo citations` check, it does not observe what engines say about a brand, and it does not cover Chinese answer engines such as Doubao, Qwen, or Yuanbao (DeepSeek is available as a `geo citations` provider).
  289. [**OpenGEO**](https://github.com/cangqiaoGEO) is a complementary open standard focused on **output-side observation**: whether engines actually mention or cite a brand, with a published interchange format. The split — readiness vs. results — is deliberate; see [#534](https://github.com/Auriti-Labs/geo-optimizer-skill/issues/534).
  290. ---
  291. ## FAQ
  292. **What is Answer Engine Optimization (AEO)?**
  293. AEO is the practice of structuring a website so AI answer engines — ChatGPT, Perplexity, Google AI Overviews, Gemini, Claude — can find, understand, and cite it as the direct answer to a user's question. It is also called Generative Engine Optimization (GEO), AI SEO, LLM SEO, or AI Search Optimization.
  294. **How do I check if ChatGPT or Perplexity cites my website?**
  295. Run `geo citations --brand "Your Brand" --domain yoursite.com` with a Perplexity or OpenAI API key. It asks the engine customer-style questions and reports whether your brand is mentioned, whether your domain is cited as a source, and which competitors are cited instead. Perplexity returns real source URLs, so it is the only LLM provider that can report your domain as cited. OpenAI and Anthropic reveal what the model knows about your brand: a URL in their answer counts as a mention, never as a citation. No account needed for the [free web version](https://geoready.dev/tools/ai-citation-checker/?utm_source=github&utm_medium=readme&utm_campaign=faq).
  296. **How do I improve my site's GEO score?**
  297. Run `geo audit --url https://yoursite.com` and read the priority list, then `geo fix --url https://yoursite.com` to preview the robots.txt rules, `llms.txt`, JSON-LD schema and meta tags it would write (`--apply` writes them), and audit again. Start where the audit shows the most missing points: among the audited sites, the largest readiness gap is AI discovery files, and the median score is 59/100 (17 October 2026). To see your own list without installing anything, [run the free web audit](https://geoready.dev/?utm_source=github&utm_medium=readme&utm_campaign=faq-start), or read the [free 160-page GEO Readiness Manual](https://geoready.dev/geo-readiness-manual/?utm_source=github&utm_medium=readme&utm_campaign=faq-start).
  298. **Does GEO Optimizer guarantee that AI engines will cite my site?**
  299. No. It measures the signals that make a site reachable, parseable, and quotable, and it tells you which ones are missing. Whether an engine cites you also depends on the question, the competition, and the engine itself — and answers change from run to run, which is why `geo citations` has `--runs`.
  300. **Is this an llms.txt generator and checker?**
  301. Yes. `geo llms` generates an `llms.txt` from your sitemap, `--check-drift` flags stale URLs, the audit scores its presence and depth, and the [Astro integration](#astro-integration) creates one at build time. There's also a [free online llms.txt generator](https://geoready.dev/tools/llms-txt-generator/?utm_source=github&utm_medium=readme&utm_campaign=faq).
  302. **What is llms.txt, and does it improve AI citations?**
  303. `llms.txt` is a Markdown file at the root of a site (`/llms.txt`) that gives language models a curated index of its most important pages. It is an organizational signal, not a proven ranking factor: no engine has documented that it improves citations. GEO Optimizer scores it because it is cheap to add and is intended to help AI systems read a site's structure.
  304. **Is it free and open source?**
  305. Yes — MIT licensed, free forever via `pip install geo-optimizer-skill` or `uvx`. The hosted [GeoReady](https://geoready.dev/?utm_source=github&utm_medium=readme&utm_campaign=faq) platform runs the same engine and adds monitoring, score history, and team features.
  306. **Which AI engines does it cover?**
  307. 27 AI crawlers, including ChatGPT (GPTBot, OAI-SearchBot), Perplexity (PerplexityBot), Claude (ClaudeBot, Claude-SearchBot), and Google (Googlebot, Google-Extended), plus per-platform readiness profiles for ChatGPT, Perplexity, and Google AI Overviews.
  308. **Is it free for commercial use?**
  309. Yes. The MIT license permits commercial use, modification, and redistribution with no fee and no attribution beyond the license notice. Agencies can run client audits and CI gates with the CLI without any paid plan. The hosted platform is optional and separate.
  310. **Does the CLI send my data anywhere?**
  311. No. The CLI fetches only the URL you audit and any AI provider you configure with your own API key (`geo citations`). There is no telemetry, no phone-home, and no account requirement — the audit runs entirely on your machine.
  312. **How long does an audit take?**
  313. A single-URL audit runs in a few seconds. A sitemap batch depends on size and the `--max-urls` cap (default 25). The full test suite of 2,000+ tests runs in CI on every push across Python 3.10–3.14.
  314. **Can I use it in CI/CD?**
  315. Yes. The GitHub Action fails the build below a score threshold and can emit SARIF findings for the GitHub Security tab. Any CI that runs Python works (GitLab, Jenkins, CircleCI), and `geo drift --fail-on warning` catches regressions between deploys.
  316. **What is the difference between GEO and AEO?**
  317. Nothing in practice — they are two names for the same discipline. AEO (Answer Engine Optimization) emphasizes the answer engine as the target; GEO (Generative Engine Optimization) is the term used in the peer-reviewed research (KDD 2024). This tool uses both terms because its audience searches for both.
  318. **How is it different from a traditional SEO tool?**
  319. Traditional SEO tools optimize for Google rankings and backlinks. GEO Optimizer measures AI *citation readiness* — whether answer engines can crawl, parse, and quote your content — using signals (llms.txt, AI-bot access, schema richness, citability, topical authority) that classic SEO tools don't score. Standard technical SEO checks (meta tags, canonical URLs, Open Graph) are audited alongside them.
  320. **What research is GEO Optimizer based on?**
  321. The *GEO: Generative Engine Optimization* paper (KDD 2024), the *C-SEO Bench* benchmark, the *AutoGEO* preprint (arXiv 2025), plus industry studies for the remaining content checks. Every check lists its source in [docs/geo-methods.md](docs/geo-methods.md).
  322. **Is there a book on Generative Engine Optimization?**
  323. Yes. *AI Search Engineering: A Technical Guide to Generative Engine Optimization (GEO), AI Citations, and Agent-Ready Websites* is a 992-page book by Juan Camilo Auriti, the author of GEO Optimizer, published 10 September 2026 (ISBN 979-8172934568). The scoring model it describes is the one implemented in this engine. See [the book](#the-book-behind-the-engine-ai-search-engineering).
  324. ---
  325. ## Roadmap
  326. Focused release waves, not noisy patches: 100 releases since February 2026, currently **v4.23.0**. Next up is the v5.0 cycle — signal architecture, retrieval surface analysis, and scoring recalibration. Calendar and direction: [docs/ROADMAP.md](docs/ROADMAP.md).
  327. ---
  328. ## Contributing
  329. ```bash
  330. git clone https://github.com/YOUR_USERNAME/geo-optimizer-skill.git
  331. cd geo-optimizer-skill && pip install -e ".[dev]"
  332. pytest tests/ -v # 2,000+ tests, HTTP mocked
  333. ```
  334. [Bug reports](https://github.com/Auriti-Labs/geo-optimizer-skill/issues/new?template=bug_report.yml) · [Feature requests](https://github.com/Auriti-Labs/geo-optimizer-skill/issues/new?template=feature_request.yml) · [CONTRIBUTING.md](CONTRIBUTING.md)
  335. **Security:** every URL input is validated against private IP ranges (RFC 1918, loopback, link-local, cloud metadata) with DNS pinning before any request. Report vulnerabilities via [SECURITY.md](SECURITY.md).
  336. ---
  337. ## Star History
  338. <a href="https://star-history.com/#Auriti-Labs/geo-optimizer-skill&type=Date">
  339. <picture>
  340. <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=Auriti-Labs/geo-optimizer-skill&type=Date&theme=dark" />
  341. <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=Auriti-Labs/geo-optimizer-skill&type=Date" />
  342. <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=Auriti-Labs/geo-optimizer-skill&type=Date" />
  343. </picture>
  344. </a>
  345. ---
  346. <div align="center">
  347. GEO Optimizer is built and maintained by [Juan Camilo Auriti](https://www.linkedin.com/in/juancamiloauriti/) ([@JuanAuriti](https://x.com/JuanAuriti)) under [Auriti Labs](https://github.com/auriti-labs). If it saved you time, a ⭐ helps other people find it, and [GitHub Sponsors](https://github.com/sponsors/auriti) funds new research-backed checks.
  348. [![Star on GitHub](https://img.shields.io/badge/Star_on_GitHub-%E2%98%85-facc15?style=for-the-badge&logo=github&logoColor=black)](https://github.com/auriti-labs/geo-optimizer-skill/stargazers)
  349. [![Sponsor](https://img.shields.io/badge/Sponsor-%E2%9D%A4-db61a2?style=for-the-badge&logo=GitHub-Sponsors&logoColor=white)](https://github.com/sponsors/auriti)
  350. [![Free hosted audit](https://img.shields.io/badge/Free_hosted_audit-geoready.dev-0D9488?style=for-the-badge)](https://geoready.dev/?utm_source=github&utm_medium=readme&utm_campaign=footer)
  351. **MIT License** · [Name and logo policy](TRADEMARKS.md) · The HTML/PDF report embeds the Stack Sans fonts under the [SIL Open Font License 1.1](src/geo_optimizer/cli/report_assets/OFL.txt)
  352. </div>
install.sh · Bundled script · 48 lines · 1 finding marked
  1. #!/usr/bin/env bash
  2. # GEO Optimizer — Installation Script
  3. # https://github.com/auriti-labs/geo-optimizer-skill
  4. #
  5. # Usage:
  6. # curl -sSL https://raw.githubusercontent.com/auriti-labs/geo-optimizer-skill/main/install.sh | bash
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 6 on GitHub
  7. # pip install geo-optimizer-skill
  8. set -e
  9. GREEN='\033[0;32m'
  10. RED='\033[0;31m'
  11. NC='\033[0m'
  12. ok() { echo -e "${GREEN}\u2705 $1${NC}"; }
  13. err() { echo -e "${RED}\u274c $1${NC}"; exit 1; }
  14. echo ""
  15. echo "\U0001f916 GEO Optimizer — Installation"
  16. echo "================================"
  17. echo ""
  18. # Verifica Python
  19. command -v python3 >/dev/null 2>&1 || err "Python 3 is required. Install it first: https://python.org"
  20. PYTHON_VER=$(python3 --version 2>&1)
  21. ok "Python found: $PYTHON_VER"
  22. # Installa da PyPI
  23. echo ""
  24. echo "\U0001f4e6 Installing geo-optimizer-skill from PyPI..."
  25. pip install geo-optimizer-skill
  26. ok "geo-optimizer-skill installed"
  27. # Verifica
  28. echo ""
  29. geo --version && ok "CLI ready!" || err "Installation failed"
  30. echo ""
  31. echo "================================"
  32. ok "Installation complete!"
  33. echo ""
  34. echo "\U0001f680 Quick start:"
  35. echo " geo audit --url https://yoursite.com"
  36. echo " geo llms --base-url https://yoursite.com --output llms.txt"
  37. echo " geo schema --type faq --url https://yoursite.com"
  38. echo ""
  39. echo "\U0001f4d6 Full docs: https://github.com/auriti-labs/geo-optimizer-skill"
  40. echo ""
src/geo_optimizer/core/competitive_narrative.py · Bundled script · 467 lines · 1 finding marked
  1. """Competitive Narrative Analysis - LLM-powered analysis of how competitors are described.
  2. Analisi narrativa competitiva: usa LLM per estrarre come i competitor vengono
  3. descritti dagli LLM (adjectives, frames, positioning). confronta il positioning
  4. con il proprio e identifica gap di narrative.
  5. Base: Princeton KDD 2024, AutoGEO (arXiv:2510.11438, preprint) - citability and content quality.
  6. """
  7. from __future__ import annotations
  8. import json as _json
  9. import logging
  10. from dataclasses import dataclass, field
  11. from typing import Any
  12. from geo_optimizer.core.audit import run_full_audit
  13. from geo_optimizer.core.llm_client import query_llm
  14. from geo_optimizer.models.results import AuditResult
  15. logger = logging.getLogger(__name__)
  16. # Pattern noti di prompt injection da rimuovere dai dati scrapati
  17. _PROMPT_INJECTION_PATTERNS = [
  18. "ignore all previous instructions",
    • Note: Quoted as data in code: Quotes instruction-override phrasing (in quotes, code, a table or an example): "ignore all previous instructions"
    • Line 25 on GitHub
  19. "ignore previous",
  20. "disregard everything",
  21. "forget everything",
  22. "### system:",
  23. "### instruction:",
  24. "### human:",
  25. "### assistant:",
  26. "### user:",
  27. "[INST]",
  28. "[/INST]",
  29. "<|im_start|>",
  30. "<|im_end|>",
  31. "<|system|>",
  32. "<|user|>",
  33. "<|assistant|>",
  34. "system:",
  35. "assistant:",
  36. ]
  37. def _sanitize_prompt_input(text: str, max_len: int = 500) -> str:
  38. """Sanitizza testo scrapato prima di interpolarlo in un LLM prompt.
  39. Rimuove pattern noti di prompt injection e tronca a max_len caratteri.
  40. """
  41. if not isinstance(text, str):
  42. text = str(text)
  43. text = text.strip()
  44. lower = text.lower()
  45. for pattern in _PROMPT_INJECTION_PATTERNS:
  46. if pattern in lower:
  47. text = text.replace(pattern, "")
  48. text = text.replace(pattern.title(), "")
  49. text = text.replace(pattern.upper(), "")
  50. text = text.replace(pattern.capitalize(), "")
  51. return text[:max_len].strip()
  52. @dataclass
  53. class CompetitorNarrative:
  54. """Narrazione estratta per un singolo competitor."""
  55. url: str
  56. brand_name: str = ""
  57. dominant_adjectives: list[str] = field(default_factory=list) # e.g., "enterprise", "budget", "premium"
  58. key_frames: list[str] = field(default_factory=list) # e.g., "AI-first", "developer-friendly"
  59. positioning: str = "" # 1-liner positioning statement
  60. credibility_signals: list[str] = field(default_factory=list) # trust indicators found
  61. content_gaps: list[str] = field(default_factory=list) # narrative elements missing
  62. confidence: float = 0.0 # LLM confidence in this analysis
  63. score: int = 0 # GEO score (from audit), for display purposes
  64. has_error: bool = False # LLM analysis failed for this competitor
  65. @dataclass
  66. class CompetitiveGap:
  67. """Gap di narrative tra il target e un competitor."""
  68. category: str # e.g., "positioning", "credibility", "features"
  69. gap_type: str # "missing", "weak", "opposing"
  70. competitor_url: str
  71. competitor_narrative: str
  72. target_missing: str
  73. suggested_content: str # cosa aggiungere per colmare il gap
  74. impact: int # punti GEO potenziali
  75. @dataclass
  76. class CompetitiveNarrativeResult:
  77. """Risultato completo dell'analisi competitiva narrativa."""
  78. target_url: str
  79. competitors: list[CompetitorNarrative] = field(default_factory=list)
  80. competitive_gaps: list[CompetitiveGap] = field(default_factory=list)
  81. summary: str = "" # executive summary
  82. llm_usage: dict[str, int] = field(default_factory=dict) # provider -> token count
  83. target_audit: AuditResult | None = None
  84. # ─── LLM Prompts ──────────────────────────────────────────────────────────────
  85. _NARRATIVE_EXTRACTOR_PROMPT = """Analyze how an AI crawler (ChatGPT, Perplexity, Claude) might describe this brand.
  86. Page info:
  87. - URL: {url}
  88. - Brand name(s): {brand_names}
  89. - H1: {h1}
  90. - Title: {title}
  91. - Description: {description}
  92. - Content word count: {word_count}
  93. - Key sections: {sections}
  94. Tasks:
  95. 1. Extract 3-5 dominant adjectives that define this brand
  96. 2. Identify 2-4 key "frames" or positioning angles (e.g. "AI-first", "developer-friendly", "enterprise-grade")
  97. 3. Write a one-line positioning statement (max 15 words)
  98. 4. Extract the credibility signals present (case studies, testimonials, certifications)
  99. 5. Flag what might be missing from the narrative (e.g. "no mention of sustainability")
  100. Respond in JSON with this structure:
  101. {{
  102. "dominant_adjectives": ["...", "..."],
  103. "key_frames": ["...", "..."],
  104. "positioning": "...",
  105. "credibility_signals": ["...", "..."],
  106. "content_gaps": ["...", "..."],
  107. "confidence": 0.85
  108. }}""".strip()
  109. _COMPETITIVE_COMPARISON_PROMPT = """Compare the positioning of two brands in the same market.
  110. Target brand (yours):
  111. - URL: {target_url}
  112. - Brand name: {target_brand}
  113. - Positioning: {target_positioning}
  114. - Key frames: {target_frames}
  115. Competitor brand:
  116. - URL: {competitor_url}
  117. - Brand name: {competitor_name}
  118. - Positioning: {competitor_positioning}
  119. - Key frames: {competitor_frames}
  120. Tasks:
  121. 1. What are the main positioning differences?
  122. 2. Which market segments does the competitor cover that the target misses?
  123. 3. Which signals does the target lack that the competitor has?
  124. 4. What content should the target create to close the gap?
  125. Respond in JSON with this structure:
  126. {{
  127. "positioning_gap": "description of the main gap",
  128. "missing_market_segment": "missing segment",
  129. "missing_signals": ["signal1", "signal2"],
  130. "suggested_content": "content idea to close the gap",
  131. "geo_impact": 3 // 1-5, estimated GEO impact
  132. }}""".strip()
  133. # ─── Core Functions ───────────────────────────────────────────────────────────
  134. def extract_competitor_narrative(url: str, audit: AuditResult) -> CompetitorNarrative:
  135. """Estrae la narrazione di un competitor usando LLM, basandosi sull'audit già eseguito.
  136. Args:
  137. url: URL del competitor
  138. audit: AuditResult già computed per questo URL
  139. Returns:
  140. CompetitorNarrative con adjectives, frames, positioning, score
  141. """
  142. result = CompetitorNarrative(url=url, score=audit.score, brand_name=audit.meta.title_text or "")
  143. # Build content summary from audit
  144. brand_names = audit.brand_entity.names_found if audit.brand_entity else []
  145. if not brand_names and audit.meta.title_text:
  146. # Fallback da meta
  147. # Estrai brand name da title (prima parte prima di separatori)
  148. for sep in (" — ", " - ", " | ", " · "):
  149. if sep in audit.meta.title_text:
  150. brand_names = [audit.meta.title_text.split(sep)[0].strip()]
  151. break
  152. if not brand_names:
  153. brand_names = [audit.meta.title_text[:100]]
  154. h1 = audit.content.h1_text if audit.content.h1_text else ""
  155. title = audit.meta.title_text or ""
  156. description = audit.meta.description_text or ""
  157. word_count = audit.content.word_count or 0
  158. # Sanitizza input scrapati prima di interpolarli nel prompt LLM
  159. safe_brand_names = [_sanitize_prompt_input(b, max_len=100) for b in brand_names[:3]]
  160. safe_h1 = _sanitize_prompt_input(h1, max_len=200)
  161. safe_title = _sanitize_prompt_input(title, max_len=200)
  162. safe_description = _sanitize_prompt_input(description, max_len=200)
  163. # Estrai section headers per contesto
  164. sections = []
  165. # Cerca H2 nel content (se available)
  166. if hasattr(audit, "_raw_html") and audit._raw_html:
  167. # Questo campo non esiste in AuditResult - use content heading_count
  168. sections = [f"H2 section (count: {audit.content.heading_count})"]
  169. else:
  170. sections = ["Headings structure present"]
  171. # Build prompt
  172. prompt = _NARRATIVE_EXTRACTOR_PROMPT.format(
  173. url=url,
  174. brand_names=", ".join(safe_brand_names) if safe_brand_names else "Unknown",
  175. h1=safe_h1 if safe_h1 else "None",
  176. title=safe_title if safe_title else "None",
  177. description=safe_description if safe_description else "None",
  178. word_count=word_count,
  179. sections=", ".join(sections),
  180. )
  181. # Query LLM
  182. system = "You are a marketing analyst specialized in AI search visibility and brand positioning."
  183. response = query_llm(prompt, system=system, max_tokens=512)
  184. if response.error:
  185. logger.warning("LLM query failed for %s: %s", url, response.error)
  186. result.positioning = "Unable to analyze - LLM unavailable"
  187. return result
  188. # Parse JSON response
  189. try:
  190. data = _json.loads(response.text)
  191. result.dominant_adjectives = data.get("dominant_adjectives", [])[:5]
  192. result.key_frames = data.get("key_frames", [])[:4]
  193. result.positioning = data.get("positioning", "")[:200]
  194. result.credibility_signals = data.get("credibility_signals", [])[:5]
  195. result.content_gaps = data.get("content_gaps", [])[:5]
  196. result.confidence = float(data.get("confidence", 0.5))
  197. except (_json.JSONDecodeError, TypeError, ValueError) as exc:
  198. logger.warning("Failed to parse LLM response for %s: %s", url, exc)
  199. # Fallback values
  200. result.positioning = "Unable to parse analysis"
  201. result.confidence = 0.0
  202. return result
  203. def run_competitive_narrative_analysis(
  204. target_url: str,
  205. competitor_urls: list[str],
  206. ) -> CompetitiveNarrativeResult:
  207. """Esegue analisi competitiva narrativa completa.
  208. Processo:
  209. 1. Audit target
  210. 2. Audit each competitor
  211. 3. Extract narrative for each competitor
  212. 4. Compare target vs competitors
  213. 5. Generate gaps and recommendations
  214. Args:
  215. target_url: URL da analizzare (il proprio sito)
  216. competitor_urls: Lista di competitor URL
  217. Returns:
  218. CompetitiveNarrativeResult con gap e recommendations
  219. """
  220. from geo_optimizer.utils.validators import normalize_url_scheme
  221. target_url = normalize_url_scheme(target_url)
  222. result = CompetitiveNarrativeResult(target_url=target_url)
  223. # Audit target
  224. try:
  225. from geo_optimizer.utils.validators import validate_public_url
  226. # Anti-SSRF validation. Scheme normalized above: validate_public_url
  227. # rejects a bare domain like "example.com" outright ("Scheme not
  228. # allowed: ''"), since it has no scheme for urlparse to read — the
  229. # same bug class fixed project-wide in normalize_url_scheme(), just
  230. # not yet applied here when this endpoint was added.
  231. safe, reason = validate_public_url(target_url)
  232. if not safe:
  233. result.summary = f"Error: Invalid target URL - {reason}"
  234. return result
  235. target_audit = run_full_audit(target_url)
  236. except Exception as exc:
  237. result.summary = f"Error auditing target: {exc}"
  238. return result
  239. result.target_audit = target_audit # Store for later use
  240. # Audit each competitor
  241. for raw_url in competitor_urls:
  242. url = normalize_url_scheme(raw_url)
  243. try:
  244. safe, reason = validate_public_url(url)
  245. if not safe:
  246. logger.warning("Skipping invalid URL: %s - %s", url, reason)
  247. continue
  248. competitor_audit = run_full_audit(url)
  249. narrative = extract_competitor_narrative(url, competitor_audit)
  250. result.competitors.append(narrative)
  251. except Exception as exc:
  252. logger.warning("Failed to audit competitor %s: %s", url, exc)
  253. # Add minimal competitor entry with error
  254. result.competitors.append(CompetitorNarrative(url=url, positioning=f"Error: {exc}"))
  255. if not result.competitors:
  256. result.summary = "Could not analyze any competitors - all URLs invalid or unavailable"
  257. return result
  258. # Generate competitive gaps
  259. result.competitive_gaps = _build_competitive_gaps(target_audit, result.competitors)
  260. # Generate summary
  261. result.summary = _build_summary(target_audit, result.competitors, result.competitive_gaps)
  262. return result
  263. def _build_competitive_gaps(
  264. target_audit: AuditResult,
  265. competitors: list[CompetitorNarrative],
  266. ) -> list[CompetitiveGap]:
  267. """Confronta target vs competitors e genera gap di narrative."""
  268. gaps: list[CompetitiveGap] = []
  269. # Extract target info
  270. target_brand = target_audit.meta.title_text or ""
  271. for sep in (" — ", " - ", " | ", " · "):
  272. if sep in target_brand:
  273. target_brand = target_brand.split(sep)[0].strip()
  274. break
  275. target_frames = []
  276. # Extract frames from content signals
  277. if target_audit.content.word_count > 1000:
  278. target_frames.append("comprehensive")
  279. if target_audit.schema.has_faq:
  280. target_frames.append("authoritative")
  281. if target_audit.signals.has_rss:
  282. target_frames.append("active")
  283. for competitor in competitors:
  284. if competitor.positioning.startswith("Error") or competitor.positioning.startswith("Unable"):
  285. continue
  286. # Determine gap type
  287. gap_type = "missing"
  288. if competitor.confidence < 0.5:
  289. gap_type = "weak"
  290. # Build gap entry
  291. if competitor.content_gaps:
  292. for gap in competitor.content_gaps[:2]: # Max 2 gaps per competitor
  293. gaps.append(
  294. CompetitiveGap(
  295. category="narrative",
  296. gap_type=gap_type,
  297. competitor_url=competitor.url,
  298. competitor_narrative=competitor.positioning,
  299. target_missing=gap,
  300. suggested_content=f"Add content addressing: {gap}",
  301. impact=2, # Default impact
  302. )
  303. )
  304. # Deduplicate
  305. seen = set()
  306. unique_gaps: list[CompetitiveGap] = []
  307. for candidate in gaps:
  308. key = (candidate.gap_type, candidate.target_missing)
  309. if key not in seen:
  310. seen.add(key)
  311. unique_gaps.append(candidate)
  312. return unique_gaps
  313. def _build_summary(
  314. target_audit: AuditResult,
  315. competitors: list[CompetitorNarrative],
  316. gaps: list[CompetitiveGap],
  317. ) -> str:
  318. """Costruisce un executive summary dell'analisi."""
  319. if not competitors:
  320. return "No competitors analyzed"
  321. # Score comparison
  322. target_score = target_audit.score
  323. # Count gaps
  324. gap_count = len(gaps)
  325. # Build summary
  326. summary = f"Target score: {target_score}/100. Analyzed {len(competitors)} competitor(s). "
  327. if gap_count > 0:
  328. summary += f"Found {gap_count} narrative gap(s) where competitors outperform target. "
  329. summary += "Focus content efforts on closing these positioning gaps."
  330. else:
  331. summary += "No significant narrative gaps detected."
  332. return summary
  333. # ─── API Helper Functions ──────────────────────────────────────────────────────
  334. def format_competitive_narrative(result: CompetitiveNarrativeResult) -> dict[str, Any]:
  335. """Format competitive narrative result as dictionary for API response."""
  336. return {
  337. "target_url": result.target_url,
  338. "target_score": result.target_audit.score if result.target_audit is not None else 0,
  339. "target_band": result.target_audit.band if result.target_audit is not None else "critical",
  340. "competitors": [
  341. {
  342. "url": c.url,
  343. "brand_name": c.brand_name,
  344. "dominant_adjectives": c.dominant_adjectives,
  345. "key_frames": c.key_frames,
  346. "positioning": c.positioning,
  347. "credibility_signals": c.credibility_signals,
  348. "content_gaps": c.content_gaps,
  349. "confidence": c.confidence,
  350. "has_error": c.has_error,
  351. }
  352. for c in result.competitors
  353. ],
  354. "competitive_gaps": [
  355. {
  356. "category": g.category,
  357. "gap_type": g.gap_type,
  358. "competitor_url": g.competitor_url,
  359. "competitor_narrative": g.competitor_narrative,
  360. "target_missing": g.target_missing,
  361. "suggested_content": g.suggested_content,
  362. "impact": g.impact,
  363. }
  364. for g in result.competitive_gaps
  365. ],
  366. "summary": result.summary,
  367. "llm_usage": getattr(result, "llm_usage", {}),
  368. }
  369. def get_competitor_narratives_for_audit(audit: AuditResult, competitor_urls: list[str]) -> list[CompetitorNarrative]:
  370. """Estrae narratives da una lista di URLs usando audit già eseguito come base.
  371. Args:
  372. audit: AuditResult (per il brand name extraction)
  373. competitor_urls: URLs da analizzare
  374. Returns:
  375. List of CompetitorNarrative
  376. """
  377. narratives = []
  378. for url in competitor_urls:
  379. narratives.append(CompetitorNarrative(url=url, brand_name=audit.meta.title_text or "Unknown"))
  380. return narratives
src/geo_optimizer/core/injection_detector.py · Bundled script · 472 lines · 1 finding marked
  1. """
  2. Prompt injection pattern detection in web content (#276).
  3. Detects 8 categories of AI manipulation in content:
  4. 1. CSS-hidden text (display:none, visibility:hidden, font-size:0)
  5. 2. Invisible Unicode characters (zero-width, RTL marks)
  6. 3. Direct LLM instructions ("ignore previous instructions", special tokens)
    • Note: Quoted as data in code: Quotes instruction-override phrasing (in quotes, code, a table or an example): "ignore previous instructions"
    • Line 7 on GitHub
  7. 4. Prompts in HTML comments (<!-- instruction: ... -->)
  8. 5. Monochrome text (color ≈ background)
  9. 6. Micro-font injection (font-size < 2px)
  10. 7. Data attribute injection (data-ai-*, data-prompt-*)
  11. 8. aria-hidden with instructional content
  12. Based on UC Berkeley EMNLP 2024: text injections can manipulate AI search rankings.
  13. """
  14. from __future__ import annotations
  15. import re
  16. from geo_optimizer.models.config import (
  17. MICROFONT_SIZE_THRESHOLD_PX,
  18. PROMPT_INJECTION_COMMENT_KEYWORDS,
  19. PROMPT_INJECTION_COMMENT_MAX_LEN,
  20. PROMPT_INJECTION_LLM_PATTERNS,
  21. PROMPT_INJECTION_MAX_SAMPLES,
  22. PROMPT_INJECTION_SAMPLE_MAX_LEN,
  23. PROMPT_INJECTION_UNICODE_THRESHOLD,
  24. UGC_ID_CLASS_RE,
  25. UGC_SCRIPT_HOSTS,
  26. UGC_WIDGET_MARKERS,
  27. )
  28. from geo_optimizer.models.results import PromptInjectionResult
  29. # ─── Compiled patterns (once at import time) ─────────────────────────────────
  30. _LLM_PATTERNS_COMPILED = [re.compile(p, re.IGNORECASE | re.DOTALL) for p in PROMPT_INJECTION_LLM_PATTERNS]
  31. _HIDDEN_CSS_PATTERNS = [
  32. re.compile(r"display\s*:\s*none", re.IGNORECASE),
  33. re.compile(r"visibility\s*:\s*hidden", re.IGNORECASE),
  34. re.compile(r"font-size\s*:\s*0(?:px|pt|em|rem)?\s*(?:;|$)", re.IGNORECASE),
  35. re.compile(r"opacity\s*:\s*0(?:\s|;|$)", re.IGNORECASE),
  36. ]
  37. _INVISIBLE_UNICODE_RE = re.compile(r"[\u200b\u200c\u200d\u200e\u200f\ufeff\u202a-\u202e\u2060]")
  38. _HTML_COMMENT_RE = re.compile(r"<!--(.*?)-->", re.DOTALL)
  39. _FONT_SIZE_RE = re.compile(r"font-size\s*:\s*([\d.]+)\s*(px|pt|em|rem)", re.IGNORECASE)
  40. _DATA_ATTR_RE = re.compile(r"^data-(?:ai|prompt|llm|instruction|context|system)-", re.IGNORECASE)
  41. _UGC_ID_CLASS_RE = re.compile(UGC_ID_CLASS_RE, re.IGNORECASE)
  42. _COLOR_HEX_RE = re.compile(r"color\s*:\s*#([0-9a-fA-F]{3,6})", re.IGNORECASE)
  43. _BG_HEX_RE = re.compile(r"background(?:-color)?\s*:\s*#([0-9a-fA-F]{3,6})", re.IGNORECASE)
  44. _RGBA_ALPHA_RE = re.compile(r"rgba?\(\s*\d+\s*,\s*\d+\s*,\s*\d+\s*,\s*(0(?:\.\d+)?)\s*\)", re.IGNORECASE)
  45. def _truncate(text: str, max_len: int = PROMPT_INJECTION_SAMPLE_MAX_LEN) -> str:
  46. """Truncate text to the maximum length with an ellipsis."""
  47. return text[:max_len] + "…" if len(text) > max_len else text
  48. def _get_text_safe(element) -> str:
  49. """Safely extract text from a BeautifulSoup element."""
  50. try:
  51. return str(element.get_text(strip=True))
  52. except Exception:
  53. return ""
  54. # ─── Category 1: CSS-hidden text ─────────────────────────────────────────────
  55. def _detect_hidden_text(soup) -> tuple[bool, int, list[str]]:
  56. """Detect text hidden via inline CSS."""
  57. found_count = 0
  58. samples: list[str] = []
  59. for el in soup.find_all(style=True):
  60. style = el.get("style", "")
  61. text = _get_text_safe(el)
  62. if len(text) < 3:
  63. continue
  64. for pattern in _HIDDEN_CSS_PATTERNS:
  65. if pattern.search(style):
  66. found_count += 1
  67. if len(samples) < PROMPT_INJECTION_MAX_SAMPLES:
  68. samples.append(_truncate(text))
  69. break
  70. return found_count > 0, found_count, samples
  71. # ─── Category 2: Invisible Unicode ───────────────────────────────────────────
  72. def _detect_invisible_unicode(soup) -> tuple[bool, int]:
  73. """Detect invisible Unicode characters in the body text."""
  74. body = soup.find("body")
  75. if not body:
  76. return False, 0
  77. text = _get_text_safe(body)
  78. matches = _INVISIBLE_UNICODE_RE.findall(text)
  79. count = len(matches)
  80. return count >= PROMPT_INJECTION_UNICODE_THRESHOLD, count
  81. # ─── Category 3: LLM instructions ────────────────────────────────────────────
  82. def _detect_llm_instructions(raw_html: str) -> tuple[bool, int, list[str]]:
  83. """Detect direct LLM instructions in the HTML content."""
  84. found_count = 0
  85. samples: list[str] = []
  86. for pattern in _LLM_PATTERNS_COMPILED:
  87. for match in pattern.finditer(raw_html):
  88. found_count += 1
  89. if len(samples) < PROMPT_INJECTION_MAX_SAMPLES:
  90. start = max(0, match.start() - 30)
  91. end = min(len(raw_html), match.end() + 30)
  92. context = raw_html[start:end].replace("\n", " ").strip()
  93. samples.append(_truncate(context))
  94. return found_count > 0, found_count, samples
  95. # ─── Category 4: HTML comments with prompts ──────────────────────────────────
  96. def _detect_html_comment_injection(raw_html: str) -> tuple[bool, int, list[str]]:
  97. """Detect prompt injection in HTML comments."""
  98. found_count = 0
  99. samples: list[str] = []
  100. for match in _HTML_COMMENT_RE.finditer(raw_html):
  101. comment = match.group(1).strip()
  102. if not comment:
  103. continue
  104. is_suspicious = False
  105. # Comment is too long
  106. if len(comment) > PROMPT_INJECTION_COMMENT_MAX_LEN:
  107. is_suspicious = True
  108. # Suspicious keywords
  109. comment_lower = comment.lower()
  110. if any(kw in comment_lower for kw in PROMPT_INJECTION_COMMENT_KEYWORDS):
  111. is_suspicious = True
  112. # LLM pattern in the comment
  113. if any(p.search(comment) for p in _LLM_PATTERNS_COMPILED):
  114. is_suspicious = True
  115. if is_suspicious:
  116. found_count += 1
  117. if len(samples) < PROMPT_INJECTION_MAX_SAMPLES:
  118. samples.append(_truncate(comment))
  119. return found_count > 0, found_count, samples
  120. # ─── Category 5: Monochrome text ─────────────────────────────────────────────
  121. def _normalize_hex(h: str) -> str:
  122. """Normalize a hex color to 6-digit lowercase."""
  123. h = h.lower()
  124. if len(h) == 3:
  125. return h[0] * 2 + h[1] * 2 + h[2] * 2
  126. return h
  127. def _detect_monochrome_text(soup) -> tuple[bool, int]:
  128. """Detect text whose color matches or is very close to the background."""
  129. found_count = 0
  130. for el in soup.find_all(style=True):
  131. style = el.get("style", "")
  132. text = _get_text_safe(el)
  133. if len(text) < 3:
  134. continue
  135. # Check rgba with transparent alpha
  136. alpha_match = _RGBA_ALPHA_RE.search(style)
  137. if alpha_match and float(alpha_match.group(1)) < 0.05:
  138. found_count += 1
  139. continue
  140. # Check hex color == background hex
  141. fg_match = _COLOR_HEX_RE.search(style)
  142. bg_match = _BG_HEX_RE.search(style)
  143. if fg_match and bg_match:
  144. fg = _normalize_hex(fg_match.group(1))
  145. bg = _normalize_hex(bg_match.group(1))
  146. if fg == bg:
  147. found_count += 1
  148. return found_count > 0, found_count
  149. # ─── Category 6: Micro-font ──────────────────────────────────────────────────
  150. def _detect_microfont(soup) -> tuple[bool, int]:
  151. """Detect elements with font-size < 2px that contain text."""
  152. found_count = 0
  153. for el in soup.find_all(style=True):
  154. text = _get_text_safe(el)
  155. if len(text) < 3:
  156. continue
  157. style = el.get("style", "")
  158. m = _FONT_SIZE_RE.search(style)
  159. if m:
  160. value = float(m.group(1))
  161. unit = m.group(2).lower()
  162. # Convert to approximate px
  163. if unit == "pt":
  164. value *= 1.33
  165. elif unit in ("em", "rem"):
  166. value *= 16
  167. if value < MICROFONT_SIZE_THRESHOLD_PX:
  168. found_count += 1
  169. return found_count > 0, found_count
  170. # ─── Category 7: Data attribute injection ────────────────────────────────────
  171. def _detect_data_attr_injection(soup) -> tuple[bool, int, list[str]]:
  172. """Detect suspicious data attributes (data-ai-*, data-prompt-*, etc.)."""
  173. found_count = 0
  174. samples: list[str] = []
  175. for el in soup.find_all():
  176. for attr_name, attr_value in el.attrs.items():
  177. if isinstance(attr_name, str) and _DATA_ATTR_RE.match(attr_name):
  178. found_count += 1
  179. if len(samples) < PROMPT_INJECTION_MAX_SAMPLES:
  180. val_str = str(attr_value)[:80] if attr_value else ""
  181. samples.append(f"{attr_name}={val_str}")
  182. return found_count > 0, found_count, samples
  183. # ─── Category 8: aria-hidden injection ───────────────────────────────────────
  184. def _is_mostly_link_text(el, total_words: int, threshold: float = 0.8) -> bool:
  185. """Report whether an element's text lives almost entirely inside anchors.
  186. Navigation is the legitimate reason for a long aria-hidden block (a collapsed
  187. mobile menu), and it is recognisable by shape: nearly every word is a link label.
  188. Args:
  189. el: The element to inspect.
  190. total_words: Word count of the element's text, already computed by the caller.
  191. threshold: Link-word ratio above which the block reads as navigation.
  192. Returns:
  193. True when at least `threshold` of the words sit inside <a> tags.
  194. """
  195. if total_words <= 0:
  196. return False
  197. link_words = sum(len(_get_text_safe(a).split()) for a in el.find_all("a"))
  198. return link_words / total_words >= threshold
  199. def _detect_aria_hidden_injection(soup) -> tuple[bool, int, list[str]]:
  200. """Detect aria-hidden elements with instructional AI content."""
  201. found_count = 0
  202. samples: list[str] = []
  203. for el in soup.find_all(attrs={"aria-hidden": "true"}):
  204. text = _get_text_safe(el)
  205. if not text:
  206. continue
  207. is_suspicious = False
  208. # Text is too long for a decorative element.
  209. #
  210. # gap #4.16.3: a collapsed mobile menu is a long aria-hidden block by design —
  211. # duplicated navigation, not concealed prose — and the length rule alone flagged
  212. # it as an injection. Skip the length rule when the text is essentially all link
  213. # labels; the LLM-instruction rule below still runs on the same text, so hiding
  214. # directives inside anchors stays detected.
  215. words = text.split()
  216. if len(words) > 50 and not _is_mostly_link_text(el, len(words)):
  217. is_suspicious = True
  218. # Contains LLM instructions
  219. if any(p.search(text) for p in _LLM_PATTERNS_COMPILED):
  220. is_suspicious = True
  221. if is_suspicious:
  222. found_count += 1
  223. if len(samples) < PROMPT_INJECTION_MAX_SAMPLES:
  224. samples.append(_truncate(text))
  225. return found_count > 0, found_count, samples
  226. # ─── UGC injection surface ──────────────────────────────────────────────────
  227. def _detect_ugc_surface(soup, raw_html: str) -> tuple[bool, list[str]]:
  228. """Detect user-generated-content regions on the page.
  229. A comments/reviews/forum area is content a third party — not the site
  230. owner — can put in front of an AI crawler. It is not an injection by
  231. itself, but it is where a poisoning payload would land, so it is worth
  232. surfacing so the owner keeps it moderated.
  233. """
  234. labels: list[str] = []
  235. haystack = raw_html.lower()
  236. # 1. Named third-party comment widgets (id/class markers or their script host).
  237. for marker, label in UGC_WIDGET_MARKERS:
  238. if marker in haystack and label not in labels:
  239. labels.append(label)
  240. for tag in soup.find_all("script", src=True):
  241. src = str(tag.get("src", "")).lower()
  242. for host in UGC_SCRIPT_HOSTS:
  243. if host in src:
  244. label = f"third-party comment script ({host})"
  245. if label not in labels:
  246. labels.append(label)
  247. # 2. Schema.org UGC types (Comment / UserComments / review markup).
  248. for el in soup.find_all(attrs={"itemtype": True}):
  249. itemtype = str(el.get("itemtype", "")).lower()
  250. if ("schema.org/comment" in itemtype or "schema.org/usercomments" in itemtype) and (
  251. "Comment schema markup" not in labels
  252. ):
  253. labels.append("Comment schema markup")
  254. review_items = soup.find_all(attrs={"itemprop": "review"})
  255. if len(review_items) >= 2 and f"review schema ({len(review_items)} reviews)" not in labels:
  256. labels.append(f"review schema ({len(review_items)} reviews)")
  257. # 3. Conventional comment/review containers with actual content in them.
  258. for el in soup.find_all(["section", "div", "ol", "ul", "article"]):
  259. ident = " ".join(
  260. [str(el.get("id", "")), " ".join(el.get("class", []) if isinstance(el.get("class"), list) else [])]
  261. ).strip()
  262. if not ident or not _UGC_ID_CLASS_RE.search(ident):
  263. continue
  264. # A real UGC region has children; an empty <div id="comments"> placeholder does too little to matter.
  265. if len(el.find_all(["li", "article", "div"], recursive=True)) < 2 and len(_get_text_safe(el)) < 40:
  266. continue
  267. label = f"'{(el.get('id') or (el.get('class') or ['?'])[0])}' region"
  268. if label not in labels:
  269. labels.append(label)
  270. if len(labels) >= 6:
  271. break
  272. return bool(labels), labels[:6]
  273. # ─── Orchestrator ─────────────────────────────────────────────────────────────
  274. def audit_prompt_injection(soup, raw_html: str) -> PromptInjectionResult:
  275. """Analyze content for prompt injection patterns.
  276. Zero HTTP requests — works only on already-available data.
  277. Args:
  278. soup: BeautifulSoup of the HTML document.
  279. raw_html: Raw HTML text for regex matching on comments and attributes.
  280. Returns:
  281. PromptInjectionResult with severity and per-category details.
  282. """
  283. result = PromptInjectionResult(checked=True)
  284. # Cat 1: CSS-hidden text
  285. result.hidden_text_found, result.hidden_text_count, result.hidden_text_samples = _detect_hidden_text(soup)
  286. # Cat 2: invisible Unicode
  287. result.invisible_unicode_found, result.invisible_unicode_count = _detect_invisible_unicode(soup)
  288. # Cat 3: LLM instructions
  289. result.llm_instruction_found, result.llm_instruction_count, result.llm_instruction_samples = (
  290. _detect_llm_instructions(raw_html)
  291. )
  292. # Cat 4: HTML comments with prompts
  293. result.html_comment_injection_found, result.html_comment_injection_count, result.html_comment_samples = (
  294. _detect_html_comment_injection(raw_html)
  295. )
  296. # Cat 5: monochrome text
  297. result.monochrome_text_found, result.monochrome_text_count = _detect_monochrome_text(soup)
  298. # Cat 6: micro-font
  299. result.microfont_found, result.microfont_count = _detect_microfont(soup)
  300. # Cat 7: data attribute injection
  301. result.data_attr_injection_found, result.data_attr_injection_count, result.data_attr_samples = (
  302. _detect_data_attr_injection(soup)
  303. )
  304. # Cat 8: aria-hidden injection
  305. result.aria_hidden_injection_found, result.aria_hidden_injection_count, result.aria_hidden_samples = (
  306. _detect_aria_hidden_injection(soup)
  307. )
  308. # UGC injection surface (advisory — not counted in severity)
  309. result.ugc_surface_found, result.ugc_surface_samples = _detect_ugc_surface(soup, raw_html)
  310. # Compute summary
  311. _compute_severity(result)
  312. # An injection pattern found *and* a UGC region present: the payload may be
  313. # third-party content the owner did not write, which changes the remediation
  314. # (moderate/exclude the UGC area, not "clean your own page").
  315. result.ugc_injection_risk = result.ugc_surface_found and result.patterns_found > 0
  316. return result
  317. def _compute_severity(result: PromptInjectionResult) -> None:
  318. """Compute severity and risk_level based on detected patterns."""
  319. categories_active = sum(
  320. [
  321. result.hidden_text_found,
  322. result.invisible_unicode_found,
  323. result.llm_instruction_found,
  324. result.html_comment_injection_found,
  325. result.monochrome_text_found,
  326. result.microfont_found,
  327. result.data_attr_injection_found,
  328. result.aria_hidden_injection_found,
  329. ]
  330. )
  331. result.patterns_found = categories_active
  332. # Severity: LLM instructions or prompts in comments are always critical
  333. if result.llm_instruction_found or result.html_comment_injection_found:
  334. result.severity = "critical"
  335. elif categories_active >= 3:
  336. result.severity = "critical"
  337. elif categories_active >= 1:
  338. result.severity = "suspicious"
  339. else:
  340. result.severity = "clean"
  341. # Granular risk level
  342. if result.llm_instruction_found or result.html_comment_injection_found or categories_active >= 3:
  343. result.risk_level = "high"
  344. elif (
  345. result.hidden_text_found
  346. or result.monochrome_text_found
  347. or result.microfont_found
  348. or result.aria_hidden_injection_found
  349. ):
  350. result.risk_level = "medium"
  351. elif result.data_attr_injection_found or result.invisible_unicode_found:
  352. result.risk_level = "low"
  353. else:
  354. result.risk_level = "none"

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.