gqllint

GraphQL anti-pattern & security analyzer -- detects query depth/complexity issues, resolver N+1 problems, over/under fetching, rate limiting & auth gaps, sch...

Security Scan

GQLLint's declared requirements, files, and runtime instructions are coherent with a local GraphQL anti-pattern scanner that optionally enforces license tiers and integrates with git hooks.

Purpose & Capability

Name/description (GraphQL anti-pattern & security analyzer) match the provided code and runtime instructions. Required binaries (git, bash, python3, jq), the license env (GQLLINT_LICENSE_KEY), lefthook install for git-hook integration, and local regex-based patterns are all consistent with a linter/scanner.

Instruction Scope

Runtime instructions and scripts only perform local file discovery and grep-based pattern matching; they read the optional license from env or ~/.openclaw/openclaw.json and can install/configure lefthook hooks. Note: the hook installer will add/append lefthook.yml in the repository and pre-push will run a full working-tree scan — this modifies project config and runs scans on local files (which may include sensitive files if present).

Install Mechanism

Install spec uses a brew formula (lefthook) — a standard package manager. There are no downloads from unknown URLs or obfuscated installers. The skill's code is included and executed locally (sourcing shell scripts), which is expected for this kind of tool.

Credentials

Primary credential GQLLINT_LICENSE_KEY is appropriate for tier gating. The license module intentionally reads ~/.openclaw/openclaw.json (declared in metadata) and may use python3/node/jq to extract the key. The code also optionally references CLAWHUB_JWT_SECRET for signature verification — this variable is not listed in metadata but is optional and only used if present.

Persistence & Privilege

always:false and normal autonomous invocation settings. The skill can install git hooks (lefthook) into a repository and will run on commit/push once installed; that repository-level change is expected for a hook-based linter but is a persistent modification to project config that users should consent to.

Assessment

This skill appears to do what it says: a local, regex-based GraphQL anti-pattern scanner with optional paid tiers enforced by a JWT license key. Before installing consider: (1) You will be asked to provide/store a license (GQLLINT_LICENSE_KEY) or the tool will look in ~/.openclaw/openclaw.json; keep the key secure. (2) The optional lefthook integration will modify or append a lefthook.yml in your repository and install pre-commit/pre-push actions that run scans on staged or full working-tree files — only install hooks if you want that behavior. (3) All scanning is local (no network calls in the provided scripts), but the tool will read repository files (so sensitive files could be scanned locally). (4) CLAWHUB_JWT_SECRET is an optional environment variable used only to verify license signatures if you set it; it is not required. If you want minimal risk, run bash "<SKILL_DIR>/scripts/dispatcher.sh" scan . manually instead of installing git hooks.

GQLLint -- GraphQL Anti-Pattern & Security Analyzer

GQLLint scans codebases for GraphQL anti-patterns: query depth/complexity issues, resolver N+1 problems, over/under fetching, rate limiting & auth gaps, schema design issues, and client query safety problems. It uses regex-based pattern matching against 90 GraphQL-specific patterns across 6 categories, lefthook for git hook integration, and produces markdown reports with actionable remediation guidance. 100% local. Zero telemetry.

Note: GQLLint focuses on GraphQL-specific patterns (schema definitions, resolvers, client queries, server configuration). It does NOT analyze general JavaScript/TypeScript quality or REST API patterns.

Commands

Free Tier (No license required)

gqllint scan [file|directory]

One-shot GraphQL quality scan of files or directories.

How to execute:

bash "<SKILL_DIR>/scripts/dispatcher.sh" --path [target]

What it does:

1. Accepts a file path or directory (defaults to current directory)
2. Discovers all source files (skips .git, node_modules, binaries, images, .min.js)
3. Runs 30 GraphQL patterns against each file (free tier limit)
4. Calculates a GraphQL quality score (0-100) per file and overall
5. Grades: A (90-100), B (80-89), C (70-79), D (60-69), F (<60)
6. Outputs findings with: file, line number, check ID, severity, description, recommendation
7. Exit code 0 if score >= 70, exit code 1 if GraphQL quality is poor
8. Free tier limited to first 30 patterns (QD + RN categories)

Example usage scenarios:

• "Scan my code for GraphQL issues" -> runs gqllint scan .
• "Check this file for N+1 resolver problems" -> runs gqllint scan src/resolvers/
• "Find query depth vulnerabilities" -> runs gqllint scan src/
• "Audit my GraphQL schema" -> runs gqllint scan .
• "Check for introspection leaks" -> runs gqllint scan .

Pro Tier ($19/user/month -- requires GQLLINT_LICENSE_KEY)

gqllint scan --tier pro [file|directory]

Extended scan with 60 patterns covering depth, N+1, fetching, and auth issues.

How to execute:

bash "<SKILL_DIR>/scripts/dispatcher.sh" --path [target] --tier pro

What it does:

1. Validates Pro+ license
2. Runs 60 GraphQL patterns (QD, RN, OF, RL categories)
3. Detects over/under fetching and missing pagination
4. Identifies auth gaps, rate limiting issues, and open playgrounds
5. Full category breakdown reporting

gqllint scan --format json [directory]

Generate JSON output for CI/CD integration.

bash "<SKILL_DIR>/scripts/dispatcher.sh" --path [directory] --format json

gqllint scan --format html [directory]

Generate HTML report for browser viewing.

bash "<SKILL_DIR>/scripts/dispatcher.sh" --path [directory] --format html

gqllint scan --category RN [directory]

Filter scan to a specific check category (QD, RN, OF, RL, SD, CQ).

bash "<SKILL_DIR>/scripts/dispatcher.sh" --path [directory] --category RN

Team Tier ($39/user/month -- requires GQLLINT_LICENSE_KEY with team tier)

gqllint scan --tier team [directory]

Full scan with all 90 patterns across all 6 categories including schema design and client safety.

How to execute:

bash "<SKILL_DIR>/scripts/dispatcher.sh" --path [directory] --tier team

What it does:

1. Validates Team+ license
2. Runs all 90 patterns across 6 categories
3. Includes schema design checks (input types, naming, JSON scalars, deprecation)
4. Includes client query safety (injection, error handling, caching, codegen)
5. Full category breakdown with per-file results

gqllint scan --verbose [directory]

Verbose output showing every matched line and pattern details.

bash "<SKILL_DIR>/scripts/dispatcher.sh" --path [directory] --verbose

gqllint status

Show license and configuration information.

bash "<SKILL_DIR>/scripts/dispatcher.sh" status

gqllint patterns

List all available detection patterns with IDs, severities, and descriptions.

bash "<SKILL_DIR>/scripts/dispatcher.sh" patterns

Check Categories

GQLLint detects 90 GraphQL anti-patterns across 6 categories:

Category	Code	Patterns	Description	Severity Range
Query Depth & Complexity	QD	15	Unbounded depth, no complexity limit, introspection leak, recursive fragments	low -- critical
Resolver N+1	RN	15	Database calls in loops, no DataLoader, sequential awaits, missing batching	low -- critical
Over/Under Fetching	OF	15	SELECT *, no pagination, eager loading, missing projections, full object returns	low -- critical
Rate Limiting & Auth	RL	15	No auth on mutations, open playground, missing rate limit, no CORS, no persisted queries	low -- critical
Schema Design	SD	15	Raw scalars in mutations, no input types, JSON scalar, naming issues, no deprecation	low -- high
Client Query Safety	CQ	15	String concatenation, template injection, no error handling, missing variables, no codegen	low -- critical

Tier-Based Pattern Access

Tier	Patterns	Categories
Free	30	QD, RN
Pro	60	QD, RN, OF, RL
Team	90	QD, RN, OF, RL, SD, CQ
Enterprise	90	QD, RN, OF, RL, SD, CQ + priority support

Scoring

GQLLint uses a deductive scoring system starting at 100 (perfect):

Severity	Point Deduction	Description
Critical	-25 per finding	Severe risk (query injection, N+1 loops, introspection leak, unauth mutations)
High	-15 per finding	Significant problem (no depth limit, no pagination, open playground, resolver waterfalls)
Medium	-8 per finding	Moderate concern (schema design gaps, missing rate limits, over-fetching)
Low	-3 per finding	Informational / best practice suggestion

Grading Scale

Grade	Score Range	Meaning
A	90-100	Excellent GraphQL quality
B	80-89	Good GraphQL with minor issues
C	70-79	Acceptable but needs improvement
D	60-69	Poor GraphQL quality
F	Below 60	Critical GraphQL problems

• Pass threshold: 70 (Grade C or better)
• Exit code 0 = pass (score >= 70)
• Exit code 1 = fail (score < 70)

Configuration

Users can configure GQLLint in ~/.openclaw/openclaw.json:

{
  "skills": {
    "entries": {
      "gqllint": {
        "enabled": true,
        "apiKey": "YOUR_LICENSE_KEY_HERE",
        "config": {
          "severityThreshold": "medium",
          "ignorePatterns": ["**/test/**", "**/fixtures/**", "**/*.test.*"],
          "ignoreChecks": [],
          "reportFormat": "text"
        }
      }
    }
  }
}

Important Notes

• Free tier works immediately with no configuration
• All scanning happens locally -- no code is sent to external servers
• License validation is offline -- no phone-home or network calls
• Pattern matching only -- no AST parsing, no external dependencies beyond bash
• Supports scanning all file types in a single pass
• Git hooks use lefthook which must be installed (see install metadata above)
• Exit codes: 0 = pass (score >= 70), 1 = fail (for CI/CD integration)
• Output formats: text (default), json, html

Error Handling

• If lefthook is not installed and user tries hooks, prompt to install it
• If license key is invalid or expired, show clear message with link to https://gqllint.pages.dev/renew
• If a file is binary, skip it automatically with no warning
• If no scannable files found in target, report clean scan with info message
• If an invalid category is specified with --category, show available categories

When to Use GQLLint

The user might say things like:

• "Scan my code for GraphQL issues"
• "Check my resolvers for N+1 problems"
• "Find query depth vulnerabilities"
• "Detect over-fetching in my GraphQL API"
• "Are there any auth gaps in my GraphQL schema?"
• "Check if introspection is enabled in production"
• "Audit my GraphQL schema design"
• "Find security issues in my GraphQL setup"
• "Check for query injection vulnerabilities"
• "Scan for missing pagination on list fields"
• "Run a GraphQL quality audit"
• "Generate a GraphQL health report"
• "Check if my resolvers use DataLoader"
• "Find N+1 database query patterns"
• "Check my client code for unsafe GraphQL patterns"