deploy-checkup 0.1.0__py3-none-any.whl

deploy_checkup/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

deploy_checkup/checks/cold_start.py

@@ -0,0 +1,37 @@
+from statistics import median
+
+from deploy_checkup.models import Finding, Level
+
+CHECK = "cold_start"
+COLD_MS = 5000  # a first request this slow usually means the server was asleep
+
+
+def check_cold_start(times_ms: list[float]) -> Finding:
+    """Compare the first response time with the ones after it."""
+    first = round(times_ms[0])
+    warm = round(median(times_ms[1:]))
+
+    if first >= COLD_MS and first > 3 * warm:
+        return Finding(
+            check=CHECK,
+            level=Level.INFO,
+            title=f"First request took {first / 1000:.1f} s, later ones {warm} ms: free tier waking up?",
+            why=(
+                "Free hosting plans often put an app to sleep when nobody visits, "
+                "and the next visitor waits while it starts again."
+            ),
+            fix=(
+                "Say so in your README so visitors know to wait, or use a plan that "
+                "keeps the server running."
+            ),
+            render_fix=(
+                "Render's free tier sleeps after 15 minutes without visitors. Say so in "
+                "your README, or move the service to a paid instance type to keep it awake."
+            ),
+        )
+
+    return Finding(
+        check=CHECK,
+        level=Level.PASS,
+        title=f"No cold start this time (first request {first} ms)",
+    )

deploy_checkup/checks/cors.py

@@ -0,0 +1,85 @@
+import httpx
+
+from deploy_checkup.models import Finding, Level
+
+CHECK = "cors"
+MADE_UP_SITE = "https://deploy-checkup-test.invalid"  # .invalid can never be a real website
+
+
+def check_cors(client: httpx.Client, api_url: str, frontend_url: str) -> list[Finding]:
+    """Ask the API as your frontend, then as a made-up site, and compare the answers."""
+    frontend = _origin(frontend_url)
+    try:
+        as_frontend = client.get(api_url, headers={"Origin": frontend})
+        as_stranger = client.get(api_url, headers={"Origin": MADE_UP_SITE})
+    except httpx.RequestError:
+        return []  # the other checks already report connection problems
+
+    return [
+        _check_own_frontend(as_frontend, frontend),
+        _check_other_sites(as_stranger),
+    ]
+
+
+def _origin(url: str) -> str:
+    """The part of a URL a browser sends as Origin: scheme, host and (if unusual) port."""
+    parsed = httpx.URL(url)
+    origin = f"{parsed.scheme}://{parsed.host}"
+    if parsed.port is not None:
+        origin += f":{parsed.port}"
+    return origin
+
+
+def _check_own_frontend(response: httpx.Response, frontend: str) -> Finding:
+    allowed = response.headers.get("access-control-allow-origin")
+    if allowed in (frontend, "*"):
+        return Finding(check=CHECK, level=Level.PASS, title=f"API allows your frontend ({frontend})")
+
+    return Finding(
+        check=CHECK,
+        level=Level.WARNING,
+        title=f"API doesn't allow your frontend ({frontend})",
+        why=(
+            "Browsers will block your frontend from reading the API's answers, "
+            "so pages that load data will break."
+        ),
+        fix=(
+            f"Add {frontend} to your API's allowed origins (often set through an "
+            "environment variable), then redeploy."
+        ),
+        render_fix=(
+            f"Add {frontend} to your API's allowed origins, for example through an "
+            "environment variable in the Render dashboard, then redeploy."
+        ),
+    )
+
+
+def _check_other_sites(response: httpx.Response) -> Finding:
+    allowed = response.headers.get("access-control-allow-origin")
+    with_cookies = response.headers.get("access-control-allow-credentials", "").lower() == "true"
+
+    if allowed is None:
+        return Finding(check=CHECK, level=Level.PASS, title="API blocks other websites")
+
+    if allowed == MADE_UP_SITE and with_cookies:
+        return Finding(
+            check=CHECK,
+            level=Level.FAIL,
+            title="API lets any website read it with your visitors' cookies",
+            why=(
+                "A stranger's site can call your API from a logged-in visitor's browser "
+                "and read their private data."
+            ),
+            fix=(
+                "List your real frontend address as the only allowed origin. "
+                "Never combine 'allow every origin' with allow_credentials."
+            ),
+        )
+
+    return Finding(
+        check=CHECK,
+        level=Level.WARNING,
+        title=f"API accepts requests from any website (Access-Control-Allow-Origin: {allowed})",
+        why="Any site can read your API's answers. That's fine for public data, risky for anything else.",
+        fix="If the API isn't meant to be public, allow only your frontend's address.",
+    )

deploy_checkup/checks/exposed_files.py

@@ -0,0 +1,65 @@
+import re
+
+import httpx
+
+from deploy_checkup.models import Finding, Level
+
+CHECK = "exposed_files"
+
+
+def _looks_like_env(body: str) -> bool:
+    return re.search(r"^[A-Z][A-Z0-9_]*=", body, re.MULTILINE) is not None
+
+
+def _looks_like_git_config(body: str) -> bool:
+    return "[core]" in body
+
+
+# Each path, and how to recognise the real file (so a friendly 200 page isn't a false alarm).
+PATHS = {
+    "/.env": _looks_like_env,
+    "/.git/config": _looks_like_git_config,
+}
+
+
+def check_exposed_files(client: httpx.Client, url: str) -> list[Finding]:
+    """Ask for a few files that should never be public, and check what comes back."""
+    findings = []
+    for path, looks_real in PATHS.items():
+        try:
+            response = client.get(httpx.URL(url).join(path))
+        except httpx.RequestError:
+            return []  # the other checks already report connection problems
+
+        is_html = "text/html" in response.headers.get("content-type", "")
+        if response.status_code == 200 and not is_html and looks_real(response.text):
+            findings.append(_exposed(path))
+        else:
+            findings.append(Finding(check=CHECK, level=Level.PASS, title=f"{path} is not exposed"))
+    return findings
+
+
+def _exposed(path: str) -> Finding:
+    return Finding(
+        check=CHECK,
+        level=Level.FAIL,
+        title=f"{path} is publicly downloadable",
+        why=(
+            "Anyone can download this file. It usually holds passwords, API keys or "
+            "your code's history, which attackers collect automatically."
+        ),
+        fix=(
+            f"Stop serving {path} (don't copy it into your build or static folder), "
+            "then change every secret it contained: assume they're already leaked."
+        ),
+    )
+
+
+def skipped() -> Finding:
+    return Finding(
+        check=CHECK,
+        level=Level.INFO,
+        title="Exposed files check skipped (needs your permission)",
+        why="It asks for files like /.env, which only the site's owner should do.",
+        fix="Run again and answer yes, or pass --yes-i-own-it in CI.",
+    )

deploy_checkup/checks/headers.py

@@ -0,0 +1,140 @@
+import httpx
+from deploy_checkup.models import Finding, Level
+
+
+CHECK = "headers"
+SIX_MONTHS= 15_552_000 #seconds
+
+def check_headers(client: httpx.Client , url:str)->list[Finding]:
+    """Check the security of the headers a browser uses to protect visitors."""
+    try:
+        response = client.get(url, follow_redirects=True)
+        
+    except httpx.RequestError:
+        return []
+    
+    headers = response.headers
+    return [
+        _check_hsts(headers),
+        _check_content_type_options(headers),
+        _check_csp(headers),
+        _check_frame_options(headers),
+        _check_referrer_policy(headers),
+    ]
+
+
+def _check_hsts(headers: httpx.Headers)->Finding:
+    value = headers.get("strict-transport-security")
+    if value is None:
+        return Finding(
+                check=CHECK,
+                level=Level.WARNING,
+                title="Strict-Transport-Security is missing",
+                why=(
+                "Without it, a visitor's browser may still try plain HTTP first, "
+                "which someone on the same Wi-Fi can intercept."
+                    ),
+                fix="Send the header Strict-Transport-Security: max-age=31536000 from your app.",        
+            )
+    
+    max_age = _parse_max_age(value)
+    if max_age is None or max_age < SIX_MONTHS:
+                return Finding(
+            check=CHECK,
+            level=Level.WARNING,
+            title=f"Strict-Transport-Security is too short ({value})",
+            why="Browsers forget the HTTPS-only rule quickly, so the protection keeps lapsing.",
+            fix="Set max-age to at least 15552000 (6 months); 31536000 (1 year) is common.",
+        )
+    return Finding(
+        check=CHECK,
+        level=Level.PASS,
+        title=f"Strict-Transport-Security is set (max-age={max_age})",
+    )          
+    
+    
+def _parse_max_age(value:str)->int|None:
+    """Return the max-age number from the HSTS value, or None if it's missing or invalid"""
+    for part in value.split(";"):
+        name,_,number = part.strip().partition("=")
+        if name.lower() == "max-age":
+            try:
+                return int(number.strip('"'))
+            except ValueError:
+                return None
+    return None
+
+
+def _check_content_type_options(headers: httpx.Headers)->Finding:
+    value = headers.get("x-content-type-options")
+    if value is None or value.strip().lower()!="nosniff":
+        return Finding(
+            check=CHECK,
+            level=Level.WARNING,
+            title="X-Content-Type-Options is not nosniff",
+            why=(
+                "The browser may guess a file's type, so an uploaded file "
+                "could be run as a script."
+            ),
+            fix="Send the header X-Content-Type-Options: nosniff from your app.",
+        )
+        
+    return Finding(check=CHECK, level=Level.PASS, title="X-Content-Type-Options is nosniff")
+
+def _check_csp(headers: httpx.Headers)-> Finding:
+    if headers.get("content-security-policy") is None:
+        return Finding(
+            check=CHECK,
+            level=Level.WARNING,
+            title="Content-Security-Policy is missing",
+            why=(
+                "If an attacker manages to inject a script into your page, the browser "
+                "will run it. A policy tells the browser which scripts are allowed."
+            ),
+            fix=(
+                "Start with Content-Security-Policy: default-src 'self' and loosen it "
+                "only for the outside sources your frontend really uses."
+            ),            
+        )
+    return Finding(check=CHECK , level=Level.PASS,title="Content-Security-Policy is set")
+
+def _check_frame_options(headers: httpx.Headers) -> Finding:
+    value = headers.get("x-frame-options", "").strip().upper()
+    csp = headers.get("content-security-policy","").strip().lower()
+    
+    if value in ("DENY","SAMEORIGIN"):
+        return Finding(check=CHECK , level=Level.PASS , title=f"X-Frame-Options is {value}")
+    
+    if "frame-ancestors" in csp:
+        return Finding(
+            check=CHECK,
+            level=Level.PASS,
+            title="X-Frame-Options isn't needed (CSP sets frame-ancestors)",
+        )
+    
+    return Finding(
+        check=CHECK,
+        level=Level.WARNING,
+        title="X-Frame-Options is missing",
+        why=(
+            "Another site can load yours inside an invisible frame and trick "
+            "visitors into clicking buttons they can't see."
+        ),
+        fix="Send X-Frame-Options: DENY, or add frame-ancestors 'none' to your CSP.",
+    )
+    
+
+def _check_referrer_policy(headers: httpx.Headers)->Finding:
+    value = headers.get("referrer-policy")
+    if value is None:
+        return Finding(
+            check=CHECK,
+            level=Level.INFO,
+            title="Referrer-Policy is not set",
+            why=(
+                "Modern browsers already default to a safe policy, but setting it "
+                "makes the behaviour the same in every browser."
+            ),
+            fix="Send Referrer-Policy: strict-origin-when-cross-origin.",
+        )
+    return Finding(check=CHECK, level=Level.PASS, title=f"Referrer-Policy is {value}")

deploy_checkup/checks/health.py

@@ -0,0 +1,106 @@
+from statistics import median
+from time import perf_counter
+
+import httpx
+
+from deploy_checkup.checks.cold_start import check_cold_start
+from deploy_checkup.models import Finding, Level
+
+CHECK = "health"
+ATTEMPTS = 3
+SLOW_MS = 1000
+
+
+def check_health(client: httpx.Client, api_url: str, path: str = "/health") -> list[Finding]:
+    """Call the health path a few times: does it exist, and how fast does it answer?"""
+    health_url = httpx.URL(api_url).join(path)
+    times_ms = []
+
+    for _ in range(ATTEMPTS):
+        start = perf_counter()
+        try:
+            response = client.get(health_url)
+        except httpx.RequestError:
+            return [_unreachable(health_url)]
+        elapsed_ms = (perf_counter() - start) * 1000
+
+        if response.status_code == 404:
+            return [_missing(health_url)]
+        if response.status_code >= 400:
+            return [_unhealthy(health_url, response.status_code)]
+
+        times_ms.append(elapsed_ms)
+
+    # The first request may include waking the server up, so judge speed on the rest.
+    return [_latency(times_ms[1:]), check_cold_start(times_ms)]
+
+
+def _unreachable(health_url: httpx.URL) -> Finding:
+    return Finding(
+        check=CHECK,
+        level=Level.FAIL,
+        title=f"Couldn't connect to the API at {health_url.host}",
+        why="Your frontend can't load any data if the API doesn't answer.",
+        fix="Check the --api address is right, then look at your API's deploy status and logs.",
+        render_fix=(
+            "Check the --api address is right, then open the API service in the Render "
+            "dashboard and look at the Events and Logs tabs."
+        ),
+    )
+
+
+def _missing(health_url: httpx.URL) -> Finding:
+    return Finding(
+        check=CHECK,
+        level=Level.WARNING,
+        title=f"No health endpoint found at {health_url.path}",
+        why=(
+            "Hosts use a health check to know when a new deploy is ready and "
+            "to restart your app if it stops responding."
+        ),
+        fix=(
+            f"Add a GET {health_url.path} route that returns 200 quickly, and point "
+            "your host's health check at it."
+        ),
+        render_fix=(
+            f"Add a GET {health_url.path} route that returns 200 quickly, then set it as "
+            "the Health Check Path in the service's Settings on Render."
+        ),
+    )
+
+
+def _unhealthy(health_url: httpx.URL, status: int) -> Finding:
+    return Finding(
+        check=CHECK,
+        level=Level.FAIL,
+        title=f"Health endpoint {health_url.path} answered with status {status}",
+        why="Your app reports itself as broken, so your host may keep restarting it.",
+        fix="Check your API's logs to see why the health route is failing.",
+        render_fix="Open the service's Logs tab on Render to see why the health route is failing.",
+    )
+
+
+def _latency(times_ms: list[float]) -> Finding:
+    """Judge already-measured response times. Kept separate so tests can pass in numbers."""
+    typical = round(median(times_ms))
+    if typical < SLOW_MS:
+        return Finding(
+            check=CHECK,
+            level=Level.PASS,
+            title=f"API answered in {typical} ms (median of {len(times_ms)})",
+        )
+
+    return Finding(
+        check=CHECK,
+        level=Level.WARNING,
+        title=f"API is slow: {typical} ms (median of {len(times_ms)})",
+        why="Every page that loads data waits this long, and visitors notice anything over a second.",
+        fix=(
+            "Look for slow database calls in the health route, and check whether the "
+            "server is short of CPU or memory."
+        ),
+        render_fix=(
+            "Check the Metrics tab on Render for CPU or memory limits, and look for "
+            "slow database calls in the health route."
+        ),
+    )

deploy_checkup/checks/https.py

@@ -0,0 +1,79 @@
+import httpx
+
+from deploy_checkup.models import Finding, Level
+
+CHECK = "https"
+PERMANENT_REDIRECTS = (301, 308)
+
+
+def check_https(client: httpx.Client, url: str) -> list[Finding]:
+    """Check that the plain http:// address sends visitors to https://."""
+    http_url = httpx.URL(url).copy_with(scheme="http")
+
+    try:
+        response = client.get(http_url, follow_redirects=True)
+    except httpx.RequestError:
+        if not _answers(client, url):
+            return []  # the whole site is down; the reachable or health check says so
+        return [
+            Finding(
+                check=CHECK,
+                level=Level.INFO,
+                title="Plain HTTP isn't served at all",
+                why="Nothing can be sent unencrypted, because the http:// address doesn't answer.",
+            )
+        ]
+
+    if response.url.scheme == "http":
+        return [
+            Finding(
+                check=CHECK,
+                level=Level.FAIL,
+                title="Your site is served over plain HTTP",
+                why=(
+                    "Visitors who type your address without https:// get an unencrypted page. "
+                    "Anyone on the same Wi-Fi can read or change what they see and send."
+                ),
+                fix=(
+                    "Turn on your host's 'redirect HTTP to HTTPS' setting, or redirect in "
+                    "your app, and make sure your domain has a TLS certificate."
+                ),
+                render_fix=(
+                    "Render redirects to HTTPS automatically on its own addresses. If you use a "
+                    "custom domain, check it shows as Verified with a certificate under "
+                    "Settings > Custom Domains."
+                ),
+            )
+        ]
+
+    first_hop = response.history[0].status_code
+    if first_hop in PERMANENT_REDIRECTS:
+        return [
+            Finding(
+                check=CHECK,
+                level=Level.PASS,
+                title=f"Plain HTTP redirects to HTTPS ({first_hop})",
+            )
+        ]
+
+    return [
+        Finding(
+            check=CHECK,
+            level=Level.WARNING,
+            title=f"Plain HTTP redirects to HTTPS, but only temporarily ({first_hop})",
+            why=(
+                "Browsers don't remember a temporary redirect, so every visit still starts "
+                "with an unencrypted request."
+            ),
+            fix="Make the redirect permanent: use status 301 or 308 instead of 302 or 307.",
+        )
+    ]
+
+
+def _answers(client: httpx.Client, url: str) -> bool:
+    """True if the site answers at all on its normal address."""
+    try:
+        client.get(url)
+    except httpx.RequestError:
+        return False
+    return True

deploy_checkup/checks/reachable.py

@@ -0,0 +1,59 @@
+import httpx
+
+from deploy_checkup.models import Finding, Level
+
+CHECK = "reachable"
+
+
+def check_reachable(client: httpx.Client, url: str) -> list[Finding]:
+    """Report whether the URL answers, and how."""
+    try:
+        response = client.get(url)
+    except httpx.RequestError:
+        return [
+            Finding(
+                check=CHECK,
+                level=Level.FAIL,
+                title="Couldn't connect to the site",
+                why="Nobody can use your app if the address doesn't answer.",
+                fix="Check the URL is right, then look at your host's deploy status and logs.",
+                render_fix=(
+                    "Check the URL is right, then open the service in the Render "
+                    "dashboard and look at the Events and Logs tabs."
+                ),
+            )
+        ]
+
+    status = response.status_code
+    title = f"Site answered with status {status}"
+
+    if status >= 500:
+        return [
+            Finding(
+                check=CHECK,
+                level=Level.FAIL,
+                title=title,
+                why="Your server hit an error, so visitors see a broken page instead of your app.",
+                fix=(
+                    "Check your server's logs. A 502 or 503 usually means the app "
+                    "crashed on startup or is still deploying."
+                ),
+                render_fix=(
+                    "Open the service's Logs tab on Render. A 502 or 503 usually means "
+                    "the app crashed on startup or is still deploying."
+                ),
+            )
+        ]
+
+    if status >= 400:
+        return [
+            Finding(
+                check=CHECK,
+                level=Level.WARNING,
+                title=title,
+                why="Visitors to this address get an error page instead of your app.",
+                fix="Check the URL is the page you meant to test, for example your home page.",
+            )
+        ]
+
+    return [Finding(check=CHECK, level=Level.PASS, title=title)]

deploy_checkup/cli.py

@@ -0,0 +1,83 @@
+import argparse
+import sys
+from collections.abc import Callable
+from importlib.metadata import version
+
+import httpx
+
+from deploy_checkup.report import print_report, to_json
+from deploy_checkup.runner import exit_code, make_client, run_checks
+
+
+def main(
+    argv: list[str] | None = None,
+    client: httpx.Client | None = None,
+    ask: Callable[[str], str] | None = None,
+) -> int:
+    parser = argparse.ArgumentParser(
+        description="Check whether your deployed app is set up safely.",
+        epilog="Only test apps you own or have permission to test.",
+    )
+    parser.add_argument(
+        "-V",
+        "--version",
+        action="version",
+        version=version("deploy-checkup"),
+        help="show the program's version number",
+    )
+    parser.add_argument("url", help="your frontend's address")
+    parser.add_argument("--api", help="your API's address, if it is separate")
+    parser.add_argument(
+        "--health-path",
+        default="/health",
+        help="the API's health check path (default: /health)",
+    )
+    parser.add_argument(
+        "--yes-i-own-it",
+        action="store_true",
+        help="skip the permission question and run the probing checks (for CI)",
+    )
+    parser.add_argument(
+        "--json",
+        action="store_true",
+        help="print the findings as JSON instead of a coloured report",
+    )
+    args = parser.parse_args(argv)
+
+    probe = _has_permission(args.url, args.yes_i_own_it, ask)
+    with client or make_client() as http:
+        results = run_checks(http, args.url, args.api, args.health_path, probe)
+
+    if args.json:
+        print(to_json(results))
+    else:
+        print_report(results)
+    return exit_code(results)
+
+
+def _has_permission(url: str, yes_i_own_it: bool, ask: Callable[[str], str] | None) -> bool:
+    """Probing checks run only with a flag or a typed "yes"; never by accident."""
+    if yes_i_own_it:
+        return True
+    if ask is None:
+        if not sys.stdin.isatty():
+            return False  # nobody is there to answer, for example in CI
+        ask = _ask_on_stderr
+    try:
+        answer = ask(
+            f"Also check {url} for exposed files like /.env? "
+            "Only say yes if you own this site or have permission to test it. [y/N] "
+        )
+    except EOFError:
+        return False  # input ran out without an answer, so treat it as "no"
+    return answer.strip().lower() in ("y", "yes")
+
+
+def _ask_on_stderr(prompt: str) -> str:
+    """Like input(), but the question goes to stderr so it never mixes into --json output."""
+    print(prompt, end="", file=sys.stderr, flush=True)
+    return input()
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

deploy_checkup/hosts.py

@@ -0,0 +1,27 @@
+from dataclasses import replace
+
+import httpx
+
+from deploy_checkup.models import Finding
+
+RENDER = "Render"
+UNKNOWN = "unknown host"
+
+
+def detect_host(client: httpx.Client, url: str) -> str:
+    """Guess where the site is hosted from the headers its responses carry."""
+    try:
+        response = client.get(url)
+    except httpx.RequestError:
+        return UNKNOWN
+
+    if "x-render-origin-server" in response.headers:
+        return RENDER
+    return UNKNOWN
+
+
+def fixes_for_host(findings: list[Finding], host: str) -> list[Finding]:
+    """On Render, swap in the Render-specific fix wherever a check wrote one."""
+    if host != RENDER:
+        return findings
+    return [replace(f, fix=f.render_fix) if f.render_fix else f for f in findings]

deploy_checkup/models.py

@@ -0,0 +1,19 @@
+from dataclasses import dataclass
+from enum import Enum
+
+
+class Level(str, Enum):
+    PASS = "pass"
+    WARNING = "warning"
+    FAIL = "fail"
+    INFO = "info"
+
+
+@dataclass(frozen=True)
+class Finding:
+    check: str
+    level: Level
+    title: str
+    why: str = ""
+    fix: str = ""  # works on any host
+    render_fix: str = ""  # replaces fix when the site is on Render

deploy_checkup/report.py

@@ -0,0 +1,72 @@
+import json
+from importlib.metadata import version
+
+from rich.console import Console
+from rich.markup import escape
+
+from deploy_checkup.models import Finding, Level
+
+COLOURS = {
+    Level.PASS: "green",
+    Level.WARNING: "yellow",
+    Level.FAIL: "red",
+    Level.INFO: "blue",
+}
+
+
+def count_levels(results: dict[str, list[Finding]]) -> dict[Level, int]:
+    """How many findings there are at each level, across every address."""
+    counts = {level: 0 for level in Level}
+    for findings in results.values():
+        for finding in findings:
+            counts[finding.level] += 1
+    return counts
+
+
+def print_report(results: dict[str, list[Finding]], console: Console | None = None) -> None:
+    """Print each address's findings, then a one-line summary."""
+    console = console or Console()
+
+    for target, findings in results.items():
+        console.rule(escape(target))
+        for finding in findings:
+            colour = COLOURS[finding.level]
+            label = finding.level.value.upper()
+            console.print(f"[bold {colour}]{label:<7}[/] {escape(finding.title)}")
+            if finding.why:
+                console.print(f"        [dim]Why:[/] {escape(finding.why)}")
+            if finding.fix:
+                console.print(f"        [dim]Fix:[/] {escape(finding.fix)}")
+        console.print()
+
+    counts = count_levels(results)
+    summary = ", ".join(
+        f"[{COLOURS[level]}]{counts[level]} {level.value}[/]" for level in Level
+    )
+    console.print(f"Summary: {summary}")
+
+
+def to_json(results: dict[str, list[Finding]]) -> str:
+    """The same findings as JSON, for scripts, CI and other tools."""
+    report = {
+        "tool": "deploy-checkup",
+        "version": version("deploy-checkup"),
+        "targets": [
+            {
+                "url": target,
+                "findings": [
+                    {
+                        "check": f.check,
+                        "level": f.level.value,
+                        "title": f.title,
+                        "why": f.why,
+                        "fix": f.fix,
+                    }
+                    for f in findings
+                ],
+            }
+            for target, findings in results.items()
+        ],
+        "summary": {level.value: count for level, count in count_levels(results).items()},
+    }
+    return json.dumps(report, indent=2)

deploy_checkup/runner.py

@@ -0,0 +1,60 @@
+from importlib.metadata import version
+
+import httpx
+
+from deploy_checkup.checks import exposed_files
+from deploy_checkup.checks.cors import check_cors
+from deploy_checkup.checks.headers import check_headers
+from deploy_checkup.checks.health import check_health
+from deploy_checkup.checks.https import check_https
+from deploy_checkup.checks.reachable import check_reachable
+from deploy_checkup.hosts import detect_host, fixes_for_host
+from deploy_checkup.models import Finding, Level
+
+USER_AGENT = f"DeployCheckup/{version('deploy-checkup')}"
+TIMEOUT = httpx.Timeout(60.0)  # Render's free tier can take ~50 s to wake up
+
+
+def make_client() -> httpx.Client:
+    """A polite client: honest User-Agent and a time limit on every request."""
+    return httpx.Client(timeout=TIMEOUT, headers={"User-Agent": USER_AGENT})
+
+
+def run_checks(
+    client: httpx.Client,
+    url: str,
+    api_url: str | None = None,
+    health_path: str = "/health",
+    probe: bool = False,
+) -> dict[str, list[Finding]]:
+    """Run every check and group the findings by the address they're about.
+
+    probe=True also runs the probing checks, which only the site's owner should run.
+    """
+    frontend = check_reachable(client, url) + check_https(client, url) + check_headers(client, url)
+    if probe:
+        frontend += exposed_files.check_exposed_files(client, url)
+    else:
+        frontend.append(exposed_files.skipped())
+    results = {url: fixes_for_host(frontend, detect_host(client, url))}
+
+    if api_url and api_url != url:
+        # Health goes first: its first request is the one that can catch a cold start.
+        api = (
+            check_health(client, api_url, health_path)
+            + check_https(client, api_url)
+            + check_cors(client, api_url, url)
+        )
+        if probe:
+            api += exposed_files.check_exposed_files(client, api_url)
+        results[api_url] = fixes_for_host(api, detect_host(client, api_url))
+
+    return results
+
+
+def exit_code(results: dict[str, list[Finding]]) -> int:
+    """1 if anything failed, otherwise 0, so CI can stop a broken deploy."""
+    for findings in results.values():
+        if any(finding.level == Level.FAIL for finding in findings):
+            return 1
+    return 0

deploy_checkup-0.1.0.dist-info/METADATA

@@ -0,0 +1,178 @@
+Metadata-Version: 2.4
+Name: deploy-checkup
+Version: 0.1.0
+Summary: Check whether your deployed app is set up safely, in plain language, with fixes for your host.
+Author: Nandhagopal
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Nandhagopal2912/deploy-checkup
+Project-URL: Issues, https://github.com/Nandhagopal2912/deploy-checkup/issues
+Keywords: deploy,security,cors,headers,https,render,cli
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Classifier: Topic :: Internet :: WWW/HTTP
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx<1,>=0.28
+Requires-Dist: rich<16,>=14
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+# deploy-checkup
+
+[![CI](https://github.com/Nandhagopal2912/deploy-checkup/actions/workflows/ci.yml/badge.svg)](https://github.com/Nandhagopal2912/deploy-checkup/actions/workflows/ci.yml)
+
+Tells you, in plain language, whether your deployed app is set up safely, and exactly how to fix what isn't on your host.
+
+> **Only test apps you own or have permission to test.** Against someone else's site, unusual requests can look like an attack and may be illegal.
+
+## Install
+
+Requires Python 3.10 or newer.
+
+```bash
+pipx install deploy-checkup
+```
+
+`pipx` installs command-line tools in their own environment ([how to install pipx](https://pipx.pypa.io/stable/installation/)). `pip install deploy-checkup` works too.
+
+## Usage
+
+```bash
+deploy-checkup https://your-frontend.onrender.com --api https://your-api.onrender.com
+```
+
+| Option | Meaning |
+|---|---|
+| `url` | Your frontend's address (required) |
+| `--api` | Your API's address, if it is separate |
+| `--health-path` | The API's health check path (default `/health`) |
+| `--yes-i-own-it` | Run the probing checks without asking (for CI) |
+| `--json` | Print the findings as JSON instead of a coloured report |
+| `-V`, `--version` | Show the version |
+| `-h`, `--help` | Show help |
+
+Example output:
+
+```
+──────────── https://your-frontend.onrender.com ────────────
+PASS    Site answered with status 200
+PASS    Plain HTTP redirects to HTTPS (301)
+WARNING Content-Security-Policy is missing
+        Why: If an attacker manages to inject a script into your page, the browser will run it. ...
+        Fix: Start with Content-Security-Policy: default-src 'self' and loosen it ...
+
+Summary: 6 pass, 1 warning, 0 fail, 0 info
+```
+
+Each finding says what was found, why it matters, and how to fix it.
+
+| Level | Meaning |
+|---|---|
+| **PASS** | Checked, and it's set up well. |
+| **WARNING** | Probably worth fixing, but your app may be fine without it. Used whenever deploy-checkup can't be sure. |
+| **FAIL** | Something is clearly broken or unsafe. Fix this first. |
+| **INFO** | Good to know, such as a check that was skipped or a hint that may not apply. |
+
+The command exits with code `1` if anything fails and `0` otherwise.
+
+### Use it in CI
+
+Run it after each deploy, so a broken setup fails the pipeline. For example, in GitHub Actions:
+
+```yaml
+- run: pip install deploy-checkup
+- run: deploy-checkup https://your-frontend.onrender.com --api https://your-api.onrender.com --yes-i-own-it
+```
+
+`--yes-i-own-it` runs the probing checks without the question nobody can answer in CI. Leave it out to run only the gentle checks.
+
+## What it checks
+
+| Check | Runs on | What it asks |
+|---|---|---|
+| **reachable** | frontend | Does the address answer, and with what status? |
+| **https** | frontend and API | Does plain `http://` redirect to `https://`, and permanently (301/308)? |
+| **headers** | frontend | Are the browser security headers set? Strict-Transport-Security (at least 6 months), X-Content-Type-Options (`nosniff`), Content-Security-Policy, X-Frame-Options (or CSP `frame-ancestors`), Referrer-Policy |
+| **cors** | API | Asks the API as your frontend, then as a made-up site (`deploy-checkup-test.invalid`). Is your frontend allowed and everyone else blocked? |
+| **health** | API | Calls the health path 3 times. Does it exist, and what's the median response time? |
+| **cold_start** | API | Was the first of those requests much slower than the rest (a free tier waking up)? Reported as a hint, not a verdict. |
+| **exposed_files** | frontend and API | Can anyone download `/.env` or `/.git/config`? **Probing:** runs only after you confirm you own the site. |
+
+The headers check skips the API on purpose: a JSON API doesn't need CSP or X-Frame-Options, and flagging them would be a false alarm.
+
+**Fix hints match your host.** When a response carries Render's `x-render-origin-server` header, fixes point to the exact place in the Render dashboard. On any other host you get general advice.
+
+### Probing checks ask first
+
+Most checks send ordinary requests any browser could send. The exposed files check asks for paths like `/.env`, which on someone else's site can look like an attack. So deploy-checkup asks *"Do you own this site?"* before running it. If nobody can answer (in CI, for example), it is skipped and the report says so, unless you pass `--yes-i-own-it`. A leaked file's contents are never shown in the report.
+
+### Polite by design
+
+Every request uses a 60-second timeout (Render's free tier can take about 50 seconds to wake up) and identifies itself as `User-Agent: DeployCheckup/<version>`, so site owners can see what called them. A full run sends a few dozen ordinary requests.
+
+### What it doesn't do
+
+deploy-checkup is a quick first look, not a full security audit:
+
+- It only sends ordinary requests. It doesn't try to break in, and it isn't a replacement for tools like OWASP ZAP.
+- CORS is tested on the one API address you give it, and health on one path.
+- Cold start detection is a guess from a few timings.
+- Fix hints are written for Render first; other hosts get general advice.
+
+## JSON output
+
+`--json` prints the same findings for scripts and CI. Only the JSON goes to standard output; the permission question goes to standard error, so you can save the report safely:
+
+```bash
+deploy-checkup https://your-frontend.onrender.com --api https://your-api.onrender.com --json > report.json
+```
+
+```json
+{
+  "tool": "deploy-checkup",
+  "version": "0.1.0",
+  "targets": [
+    {
+      "url": "https://your-api.onrender.com",
+      "findings": [
+        {"check": "health", "level": "pass", "title": "API answered in 108 ms (median of 2)", "why": "", "fix": ""}
+      ]
+    }
+  ],
+  "summary": {"pass": 16, "warning": 0, "fail": 0, "info": 0}
+}
+```
+
+The exit code is the same as for the coloured report.
+
+## Development
+
+```bash
+git clone https://github.com/Nandhagopal2912/deploy-checkup.git
+cd deploy-checkup
+python -m venv .venv
+.venv\Scripts\activate          # Windows; on macOS/Linux: source .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```
+
+`-e` installs in editable mode, so code changes take effect without reinstalling. Re-run the install after changing `dependencies` or `[project.scripts]` in `pyproject.toml`.
+
+Tests never touch the network. Each check receives an `httpx.Client`, and tests pass one built on `httpx.MockTransport`, which answers requests with fake responses. CI runs them on Python 3.10 and 3.13.
+
+[`demo/`](https://github.com/Nandhagopal2912/deploy-checkup/tree/main/demo) holds a deliberately broken app with known flaws, used to prove each check catches what it should. The project's plan is in the [roadmap](https://github.com/Nandhagopal2912/deploy-checkup/blob/main/docs/Deploy%20Doctor%20Roadmap.pdf).
+
+## License
+
+[MIT](https://github.com/Nandhagopal2912/deploy-checkup/blob/main/LICENSE)

deploy_checkup-0.1.0.dist-info/RECORD

@@ -0,0 +1,21 @@
+deploy_checkup/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+deploy_checkup/__main__.py,sha256=k1ocEWawweo1qCJWNFAAvyxz3tcY13dzvCenHszij30,48
+deploy_checkup/cli.py,sha256=0tRVmYpru6b4fAPdCzDD2qqkxPR2rQr6SCLpTeUnZYU,2683
+deploy_checkup/hosts.py,sha256=rtOsEct6oe6efgLpUN1AbgrGZ-mJkoczA20EhpaRaFk,748
+deploy_checkup/models.py,sha256=7GlO-S2y9jvpZj2KPCVocnjrLYSk79w9muw23H3uDUA,372
+deploy_checkup/report.py,sha256=Cmv3mrWjuRwc8YMqWQj4w7lv5TYIB_7BVrEcRV5XVEQ,2353
+deploy_checkup/runner.py,sha256=sOpzlKIzyrl-LGKTZfnKv8ApCU-f_asqr-49abmtHeA,2232
+deploy_checkup/checks/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+deploy_checkup/checks/cold_start.py,sha256=86ZeCOxe1JYpHY56JrVI6LakloXgdE0VmWgCnhyrFsw,1331
+deploy_checkup/checks/cors.py,sha256=l_yacNx87sbozoV6WIwlRX0mg6swvMYMMPic8NKHsic,3262
+deploy_checkup/checks/exposed_files.py,sha256=x8B54c5Wh4WviZN85FJrzGiudcUpSkhSXQE6KRyK9nk,2088
+deploy_checkup/checks/headers.py,sha256=dsRj5CgW4RffabpzolQLNCwCvPsUiVk-4ZsptW_MP8o,5170
+deploy_checkup/checks/health.py,sha256=ud0bEbiXwMsHbPIlVhhNl43-M2z6A-DMBsZSnjkNnxE,3811
+deploy_checkup/checks/https.py,sha256=8dXkTQNGV9EQHxaXMGc-GGmeaJw9ZOihqtX-OAWPXus,2737
+deploy_checkup/checks/reachable.py,sha256=wkmKiQUP5jodYzRfEOmeeDx47hQr_1WCU_Bi0b_hkCw,2024
+deploy_checkup-0.1.0.dist-info/licenses/LICENSE,sha256=T05KEB9aLILkU72gnV6cl_GeYeM3XH48jVChayziiE8,1070
+deploy_checkup-0.1.0.dist-info/METADATA,sha256=vBRh2yrsV_xtJW8l_IAmufGYTzC7oyy9hPJ0Rfq0agE,8039
+deploy_checkup-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+deploy_checkup-0.1.0.dist-info/entry_points.txt,sha256=khu9uZERFBtIG91pPm9mMAGCT_R6rmbKNhpJUN4lIAY,59
+deploy_checkup-0.1.0.dist-info/top_level.txt,sha256=YDLxIPeyvP8VG-O7x7oAVzdluCQfOHxbrAC6rbq1u5Q,15
+deploy_checkup-0.1.0.dist-info/RECORD,,

deploy_checkup-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

deploy_checkup-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+deploy-checkup = deploy_checkup.cli:main

deploy_checkup-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nandha Gopal 
+
+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.

deploy_checkup-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+deploy_checkup