tk-scan Free

Fast HTTP health checker with security headers analysis, stale URL detection, and SEO audit. Zero dependencies — uses only Node.js built-in modules.

bash

npm install -g @tk-tis/tk-scan
# or run directly
npx @tk-tis/tk-scan https://your-site.com

Usage

bash

# Basic health check
tk-scan https://myapp.com

# JSON output for CI/CD pipelines
tk-scan https://myapp.com --json

# Check specific routes
tk-scan https://myapp.com --routes /,/login,/api/health

# Custom pass/fail threshold
tk-scan https://myapp.com --threshold 90

# Verbose output with issue details per route
tk-scan https://myapp.com --verbose

# Disable colors for CI logs
tk-scan https://myapp.com --no-color

# Report results to HTK-Cloud dashboard
tk-scan https://myapp.com --report https://htk-cloud-v4.enzu-agent.workers.dev/api/test-engine/external-report

# Use a config file
tk-scan --config scan-config.json

Options

Flag	Description	Default
`--json`	Output raw JSON instead of formatted console output	`false`
`--verbose`, `-v`	Show full response details and issues per route	`false`
`--threshold <N>`	Pass/fail score threshold (0-100)	`80`
`--routes <list>`	Comma-separated routes to check	`/`
`--no-color`	Disable ANSI color codes	`false`
`--report <url>`	POST results to an HTK-Cloud endpoint	—
`--config <path>`	Load options from a JSON config file	—
`--help`, `-h`	Show help message	—

What It Checks

tk-scan evaluates multiple categories in a single run:

Check	Description
HTTP Status	Verifies every route returns a 2xx or 3xx status code
Response Time	Flags slow responses: over 1s (yellow warning), over 3s (red critical)
Body Size	Flags empty or near-empty pages (under 100 characters)
App Crash Detection	Detects React error boundaries, ChunkLoadError, and similar crash indicators
Security Headers	Checks 6 headers: HSTS, X-Frame-Options, X-Content-Type-Options, CSP, Referrer-Policy, Permissions-Policy
Stale URLs	Detects references to old API versions in HTML and JavaScript
SEO	Checks for noindex meta tag and title tag presence
CSP Meta	Validates Content-Security-Policy meta tags (e.g., frame-ancestors must be an HTTP header)
CORS	OPTIONS preflight check for wildcard origin misconfiguration

Score Calculation

The score is calculated as a percentage of passed checks across all categories:

Routes — Each route's HTTP status, body content, crash detection
Security Headers — 6 headers checked individually
CORS — No wildcard origin issues
SEO — noindex presence, title tag
Stale URLs — No old API references found
CSP — No invalid meta CSP directives

Default pass threshold: 80/100

Config File

Create a scan-config.json file for repeatable scans:

json

{
  "url": "https://myapp.com",
  "routes": ["/", "/login", "/api/health", "/settings"],
  "threshold": 80,
  "stalePatterns": ["old-api-v1", "legacy-endpoint"]
}

Run it with:

bash

tk-scan --config scan-config.json

Output Format

Console Output

By default, tk-scan prints a formatted report with color-coded results showing routes, security headers, CORS status, SEO checks, and a summary score.

JSON Output

With --json, the output is a single JSON object:

json

{
  "url": "https://myapp.com",
  "score": 85,
  "status": "PASS",
  "duration": 1240,
  "timestamp": "2026-03-31T10:00:00.000Z",
  "routes": [
    {
      "route": "/",
      "status": 200,
      "duration": 340,
      "bodySize": 14280,
      "title": "My App",
      "passed": true,
      "issues": []
    }
  ],
  "security": {
    "headers": {
      "strict-transport-security": "max-age=31536000; includeSubDomains",
      "x-frame-options": "DENY",
      "x-content-type-options": "nosniff",
      "content-security-policy": "default-src 'self'",
      "referrer-policy": null,
      "permissions-policy": "camera=(), microphone=()"
    }
  },
  "cors": {
    "status": 200,
    "allowedOrigin": "*",
    "issues": []
  },
  "seo": {
    "hasNoindex": false,
    "hasTitle": true
  },
  "issues": [
    {
      "type": "missing_security_header",
      "severity": "medium",
      "detail": "Referrer-Policy header is missing"
    }
  ]
}

Exit Codes

Code	Meaning
`0`	PASS — score is greater than or equal to threshold
`1`	FAIL — score is below threshold, or a scan error occurred

Programmatic Usage

javascript

const { scan } = require('@tk-tis/tk-scan');

const result = await scan('https://myapp.com', {
  routes: ['/', '/login', '/api/health'],
  threshold: 80,
  stalePatterns: ['old-api-v1'],
});

console.log(result.score);   // 85
console.log(result.status);  // "PASS"
console.log(result.issues);  // [{ type: 'missing_security_header', ... }]

Cloud Reporter

javascript

const { scan } = require('@tk-tis/tk-scan');
const { reportToCloud } = require('@tk-tis/tk-scan/src/reporter');

const result = await scan('https://myapp.com');
await reportToCloud(result, {
  endpoint: 'https://htk-cloud-v4.enzu-agent.workers.dev/api/test-engine/external-report',
  token: 'your-auth-token',
});

Edit this page on GitHub