shield-checkup 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SherDore
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,106 @@
+# shield-checkup
+
+[![CI](https://github.com/sherdore/shield-checkup/actions/workflows/ci.yml/badge.svg)](https://github.com/sherdore/shield-checkup/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/shield-checkup.svg)](https://www.npmjs.com/package/shield-checkup)
+[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
+
+A one-command baseline security scan for any website. Point it at a URL and
+find out in seconds whether it's leaking a `.git` folder, an `.env` file, a
+database backup, or is just missing basic security headers — the kind of
+mistakes that are trivial to find and embarrassing to have.
+
+```
+npx shield-checkup example.com
+```
+
+## What it checks
+
+8 platform-agnostic, black-box checks — nothing that needs credentials or
+special access, the same category of thing a real attacker's first automated
+pass would try:
+
+- Exposed `.git` directory
+- Exposed `.env` file
+- Exposed backup files (`.sql`, `.zip`, `.bak`, etc.)
+- Directory listing enabled
+- Missing security headers (HSTS, CSP, X-Frame-Options, and more)
+- Server/framework version disclosure
+- Exposed JS/CSS source maps
+- Exposed `.DS_Store`
+
+This is **8 of [SherDore Shield](https://shield.sherdore.com)'s 35+ checks** —
+the rest are platform-specific packs (WordPress, Laravel, Node, Python,
+Magento) plus malware detection and uptime/SSL monitoring, which need a real
+scan against a verified site, not an anonymous CLI call. This tool runs the
+scan **server-side** against Shield's own API — nothing about how a check
+works ships in this package, so there's no detection logic to inspect or
+copy here, just the client.
+
+## Sample
+
+```
+  example.com
+  8 baseline checks run   0 critical   1 high   1 medium   0 low
+
+  ✗ Exposed .git directory (high)
+      🔒 full detail + remediation — unlock with a free Shield account
+  ▲ Security response headers are missing (medium)
+      Not sent on the homepage: Content-Security-Policy (limits XSS / data exfiltration)
+      → Add the missing headers at the web server or application layer.
+
+  This is 8 of Shield's 35+ checks. Get the full scan — WordPress, Laravel,
+  Node, Python, and Magento packs, plus malware detection and monitoring:
+  https://shield.sherdore.com/register?utm_source=cli&utm_medium=shield-checkup&domain=example.com
+```
+
+The lowest-severity finding(s) show full evidence and remediation right in
+the terminal — a real, honest taste of what the full product gives you.
+Everything more serious is flagged but locked, since walking through exactly
+how it was found isn't something to hand out anonymously over the network.
+
+## Usage
+
+```bash
+npx shield-checkup https://example.com
+
+# machine-readable, e.g. in a pipeline
+npx shield-checkup example.com --json
+```
+
+### Options
+
+| Flag | Description |
+| --- | --- |
+| `--json` | Output the full result as JSON instead of a report |
+| `--timeout <ms>` | Request timeout (default `15000`) |
+| `--no-color` | Disable coloured output (also respects `NO_COLOR`) |
+| `-h, --help` | Help |
+| `-v, --version` | Version |
+
+### Exit codes
+
+| Code | Meaning |
+| --- | --- |
+| `0` | No critical or high findings |
+| `1` | At least one critical or high finding — fail the build |
+| `2` | The request failed, you're rate-limited, or the URL is invalid |
+
+## How it works
+
+The CLI is a thin client — it makes one API call to
+`shield.sherdore.com/api/v1/public/quick-scan`, which runs the 8 checks above
+against your URL and returns the result. Rate-limited to keep it fair for
+everyone. Requires **Node 18.17+**.
+
+## Contributing
+
+Issues and PRs on the CLI itself (output, flags, packaging) are welcome.
+`npm run typecheck && npm run lint && npm run build` should pass. The scan
+logic lives server-side and isn't part of this repo.
+
+---
+
+Built and maintained by **[SherDore](https://www.sherdore.com)**. Shield
+monitors websites for malware, vulnerabilities, uptime, and SSL/domain
+expiry — [start a free scan](https://shield.sherdore.com) to see everything
+this teaser doesn't show you.

package/dist/cli.js

@@ -0,0 +1,179 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { parseArgs } from "util";
+
+// src/version.ts
+var VERSION = "0.1.0";
+var USER_AGENT = `shield-checkup/${VERSION} (+https://github.com/sherdore/shield-checkup)`;
+
+// src/api.ts
+var API_URL = "https://shield.sherdore.com/api/v1/public/quick-scan";
+var ApiError = class extends Error {
+};
+async function runQuickScan(url, timeoutMs) {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), timeoutMs);
+  let response;
+  try {
+    response = await fetch(API_URL, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Accept: "application/json",
+        "User-Agent": USER_AGENT
+      },
+      body: JSON.stringify({ url }),
+      signal: controller.signal
+    });
+  } catch (e) {
+    throw new ApiError(`could not reach shield.sherdore.com \u2014 ${e instanceof Error ? e.message : String(e)}`);
+  } finally {
+    clearTimeout(timeout);
+  }
+  if (response.status === 429) {
+    throw new ApiError("rate limited \u2014 try again in a minute");
+  }
+  if (response.status === 422) {
+    const body = await response.json().catch(() => null);
+    throw new ApiError(body?.errors?.url?.[0] ?? "that URL doesn't look valid");
+  }
+  if (!response.ok) {
+    throw new ApiError(`unexpected response from shield.sherdore.com (${response.status})`);
+  }
+  return await response.json();
+}
+
+// src/colors.ts
+import { createColors } from "picocolors";
+var current = createColors();
+function configureColor(enabled) {
+  current = createColors(enabled);
+}
+function colors() {
+  return current;
+}
+
+// src/render.ts
+function renderJson(report) {
+  return JSON.stringify(report, null, 2) + "\n";
+}
+function renderHuman(report) {
+  const c = colors();
+  const mark = {
+    critical: c.red("\u2717"),
+    high: c.red("\u2717"),
+    medium: c.yellow("\u25B2"),
+    low: c.yellow("\u25B2")
+  };
+  const out = [""];
+  out.push(`  ${c.bold(report.domain)}`);
+  out.push(
+    `  ${c.dim(`${report.checks_run} baseline checks run`)}   ${c.red(`${report.severity_counts.critical} critical`)}   ${c.red(`${report.severity_counts.high} high`)}   ${c.yellow(`${report.severity_counts.medium} medium`)}   ${c.yellow(`${report.severity_counts.low} low`)}`
+  );
+  out.push("");
+  if (report.findings.length === 0) {
+    out.push(`  ${c.green("\u2713")} Nothing found by the baseline checks \u2014 nice.`);
+    out.push("");
+  } else {
+    for (const finding of report.findings) {
+      out.push(`  ${mark[finding.severity]} ${c.bold(finding.title)} ${c.dim(`(${finding.severity})`)}`);
+      if (finding.locked) {
+        out.push(`      ${c.dim("\u{1F512} full detail + remediation \u2014 unlock with a free Shield account")}`);
+      } else {
+        if (finding.evidence) {
+          out.push(`      ${c.dim(finding.evidence)}`);
+        }
+        if (finding.remediation) {
+          out.push(`      ${c.dim(`\u2192 ${finding.remediation}`)}`);
+        }
+      }
+    }
+    out.push("");
+  }
+  out.push(`  ${c.cyan("This is 8 of Shield's 35+ checks.")} Get the full scan \u2014 WordPress, Laravel,`);
+  out.push(`  Node, Python, and Magento packs, plus malware detection and monitoring:`);
+  out.push(`  ${c.underline(report.unlock_url)}`);
+  out.push("");
+  return out.join("\n") + "\n";
+}
+
+// src/cli.ts
+var HELP = `
+shield-checkup ${VERSION}
+Free baseline security scan for any website \u2014 powered by SherDore Shield.
+
+USAGE
+  npx shield-checkup <url> [options]
+
+OPTIONS
+  --json          Output machine-readable JSON instead of a report
+  --timeout <ms>  Request timeout (default: 15000)
+  --no-color      Disable coloured output
+  -h, --help      Show this help
+  -v, --version   Print the version
+
+EXIT CODE
+  0  no critical or high findings
+  1  at least one critical or high finding (useful in CI)
+  2  the request failed / bad arguments
+
+This runs 8 of Shield's 35+ baseline checks (exposed .git/.env/backup
+files, missing security headers, directory listing, version disclosure,
+source maps). Full platform-aware scans, malware detection, and
+uptime/SSL monitoring: https://shield.sherdore.com
+
+Built by SherDore \u2014 https://www.sherdore.com
+`;
+function fail(message) {
+  process.stderr.write(`${colors().red("error:")} ${message}
+`);
+  process.exit(2);
+}
+async function main() {
+  const { values, positionals } = parseArgs({
+    allowPositionals: true,
+    options: {
+      json: { type: "boolean", default: false },
+      timeout: { type: "string" },
+      "no-color": { type: "boolean", default: false },
+      help: { type: "boolean", short: "h", default: false },
+      version: { type: "boolean", short: "v", default: false }
+    }
+  });
+  configureColor(values["no-color"] ? false : void 0);
+  if (values.help) {
+    process.stdout.write(HELP);
+    return 0;
+  }
+  if (values.version) {
+    process.stdout.write(`${VERSION}
+`);
+    return 0;
+  }
+  const target = positionals[0];
+  if (!target) {
+    process.stderr.write(HELP);
+    fail("a URL is required");
+  }
+  const timeoutMs = Number(values.timeout) > 0 ? Number(values.timeout) : 15e3;
+  if (!values.json) {
+    process.stderr.write(`${colors().dim(`Scanning ${target} \u2026`)}
+`);
+  }
+  try {
+    const report = await runQuickScan(target, timeoutMs);
+    process.stdout.write(values.json ? renderJson(report) : renderHuman(report));
+    return report.severity_counts.critical > 0 || report.severity_counts.high > 0 ? 1 : 0;
+  } catch (e) {
+    if (e instanceof ApiError) {
+      fail(e.message);
+    }
+    throw e;
+  }
+}
+main().then((code) => process.exit(code)).catch((e) => {
+  process.stderr.write(`${e instanceof Error ? e.stack : String(e)}
+`);
+  process.exit(2);
+});

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "shield-checkup",
+  "version": "0.1.0",
+  "description": "Free baseline security scan for any website — powered by SherDore Shield.",
+  "keywords": [
+    "security",
+    "website",
+    "scanner",
+    "vulnerability",
+    "security-headers",
+    "cli"
+  ],
+  "license": "MIT",
+  "author": "SherDore (https://www.sherdore.com)",
+  "homepage": "https://github.com/sherdore/shield-checkup#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sherdore/shield-checkup.git"
+  },
+  "bugs": {
+    "url": "https://github.com/sherdore/shield-checkup/issues"
+  },
+  "type": "module",
+  "bin": {
+    "shield-checkup": "dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18.17"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "start": "node dist/cli.js",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "picocolors": "^1.1.1"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.17.0",
+    "@types/node": "^22.10.5",
+    "eslint": "^9.17.0",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.3",
+    "typescript-eslint": "^8.19.1"
+  }
+}