code-guardian-mcp 0.2.0__py3-none-any.whl

code_guardian/__init__.py

@@ -0,0 +1,8 @@
+"""code-guardian: is this codebase safe to run, will it work, and is it complete?
+
+Deterministic Safe, Works and Complete scores (0-100) with an Overall A-F grade, from static scanners, a static call
+graph and project-file checks, plus an optional plain-English explanation from a local model that never changes the
+score. Standard library only; the scanned code is parsed, never executed, imported or installed.
+"""
+
+__version__ = "0.2.0"  # keep equal to pyproject.toml version and mcp_server.VERSION

code_guardian/__main__.py

@@ -0,0 +1,6 @@
+"""python -m code_guardian scan PATH ..."""
+import sys
+
+from .cli import main
+
+sys.exit(main())

code_guardian/catalogue.py

@@ -0,0 +1,216 @@
+"""The check catalogue: every finding code, what it means, how to fix it, and when it can be wrong.
+
+SARIF rules and the Markdown output read it; tests/test_readme_sync.py checks the README catalogue against it.
+
+Public contract:
+    CATALOGUE = {code: {"title", "means", "fix", "false_positives"}}
+"""
+
+import sys
+
+from .finding import summarize
+
+
+def _e(title, means, fix, false_positives):
+    return {"title": title, "means": means, "fix": fix, "false_positives": false_positives}
+
+
+CATALOGUE = {
+    # Safe
+    "secret.key": _e(
+        "Secret in the source",
+        "An API-key shape (OpenAI-style sk-, GitHub, Google, AWS, Stripe live, Slack, Hugging Face and others), an AWS "
+        "secret key, a private-key block, a password-like literal or a high-entropy literal in a name ending _KEY or _TOKEN is "
+        "written into a file (a Stripe test key is INFO).",
+        "Move it to an environment variable or a secret store, and rotate it: it is in the history.",
+        "Test fixtures and documentation samples; values that call themselves fake (mock, dummy, example) are skipped."),
+    "exec.dynamic": _e(
+        "Code built at runtime",
+        "eval, exec or compile runs a non-literal string, or __import__ loads a module named at runtime; FAIL when "
+        "eval or exec runs text from input(), sys.argv, request data, the environment or the network.",
+        "Use a parser, a lookup table or ast.literal_eval; import modules by name; never run input as code.",
+        "Plugin loaders and REPL-style tools use these on purpose."),
+    "exec.shell": _e(
+        "Shell command",
+        "os.system, os.popen or subprocess with shell=True; FAIL when the command text comes from input, the environment "
+        "or the network.",
+        "Pass an argument list without shell=True; validate any outside value against an allow-list.",
+        "Fixed command strings in build scripts are WARN, not FAIL; taint is tracked one function deep."),
+    "deser.unsafe": _e(
+        "Unsafe deserialisation",
+        "pickle, marshal, yaml.load without SafeLoader, or torch.load without weights_only=True can run code hidden in "
+        "the data.",
+        "Load only files you created, or use a data-only format (json, safetensors, yaml.safe_load).",
+        "Caches the program writes and reads itself are lower risk."),
+    "net.egress": _e(
+        "Network egress",
+        "The egress inventory: every URL and IP literal and every network call site. WARN for a public IP, or plain "
+        "http/ws/ftp to a public name or to a host set at runtime.",
+        "Use https, and confirm each destination is expected.",
+        "Local-network and documentation hosts stay INFO; a URL in a help string is still inventoried."),
+    "net.bind_all": _e(
+        "Listens on every interface",
+        "A server binds 0.0.0.0 or ::, so other machines can reach it.",
+        "Bind to 127.0.0.1 unless other machines must connect.",
+        "Containers usually must bind 0.0.0.0; a test that asserts the bind is refused still matches."),
+    "tls.off": _e(
+        "TLS checking switched off",
+        "verify=False, ssl._create_unverified_context, CERT_NONE or check_hostname = False.",
+        "Remove it; point at a CA bundle if the certificate is private.",
+        "Rare: code that deliberately probes broken servers."),
+    "install.hook": _e(
+        "Code runs on install",
+        "setup.py cmdclass or install-command subclasses, package.json preinstall/install/postinstall, or an in-tree "
+        "build backend.",
+        "Read what the hook runs before installing; prefer packages without install-time code.",
+        "Projects that compile extensions legitimately customise build commands."),
+    "obfuscation": _e(
+        "Obfuscated code",
+        "exec/eval of base64, zlib, marshal or hex-decoded data (FAIL); long encoded blobs or high-entropy literals (WARN).",
+        "Decode the payload offline and read what it does before running anything.",
+        "Embedded icons, test vectors and hashes can look like blobs."),
+    "fs.outside": _e(
+        "Writes outside the project",
+        "A write, delete or move aimed at an absolute path, the home directory or a .. escape.",
+        "Write under the project or under a path the user passes in.",
+        "Tools whose job is to write to /tmp or a user config folder."),
+    "deps.unpinned": _e(
+        "Unpinned dependency",
+        "A dependency with no pin and no upper bound.",
+        "Pin it (==) or cap it (< next major).",
+        "Libraries often prefer open ranges on purpose; INFO, never scored."),
+    "supply.unknown_package": _e(
+        "Unknown or invented package",
+        "Offline: the name is not in the bundled list of known packages (INFO). Online: PyPI has no such project (FAIL), "
+        "or it is new or has a single release (WARN).",
+        "Check the name is the one you meant; remove names an assistant invented; run with --online.",
+        "Offline misses are common for less-known real packages, which is why they are INFO. Existing is not safe."),
+    "supply.lookalike": _e(
+        "Lookalike package name",
+        "The name is one or two edits away from a known package without being it: the typosquatting pattern.",
+        "Check you meant the well-known package.",
+        "Real packages with names close to a popular one."),
+    # Works
+    "works.syntax": _e(
+        "File does not parse",
+        "ast.parse rejects the file, so it cannot be imported or run (INFO when the project needs a newer Python than "
+        "the one scanning).",
+        "Fix the syntax error; port Python 2 code to Python 3.",
+        "Files kept on purpose for another interpreter, or templates with a .py name."),
+    "works.import_unresolved": _e(
+        "Import nothing provides",
+        "An absolute import that is not in the standard library, not in the repo and not a declared dependency.",
+        "Declare the distribution that provides it, or guard an optional import with try/except ImportError.",
+        "Packages pulled in only by another dependency (they work by accident); import names the mapping table misses."),
+    "works.relative_missing": _e(
+        "Relative import to nothing",
+        "from .x import y points at a module (or a package name) the repo does not have.",
+        "Fix the module path or add the missing module.",
+        "Modules generated at build time."),
+    "works.tests_missing": _e(
+        "No tests",
+        "There are no test files at all.",
+        "Add a tests/ folder with at least one test per entry point.",
+        "Tests kept in another repository."),
+    "works.test_no_assert": _e(
+        "Tests that check nothing",
+        "Test functions with no assert, no pytest.raises/warns, no self.assert* and no call to an asserting helper.",
+        "Assert on the result; use pytest.raises for expected errors.",
+        "Smoke tests that only check nothing raises; helpers defined in another file."),
+    "works.entry_missing": _e(
+        "Command points at nothing",
+        "A [project.scripts] (or setup.cfg console script) target module:function is not in the tree.",
+        "Point the script at an existing module:function.",
+        "Modules generated at build time."),
+    "orphan.dead": _e(
+        "Dead code",
+        "A function, class or module nothing reachable from the entry points uses.",
+        "Delete it, or list it in keep if something loads it by name.",
+        "Code loaded by name (plugins, entry points of other tools); add those to keep."),
+    "orphan.test_only": _e(
+        "Used only by tests",
+        "Only tests reach this code; the product never does.",
+        "Delete it with its tests, or call it from the product.",
+        "Test helpers kept in the package on purpose."),
+    "orphan.uncertain": _e(
+        "Maybe used dynamically",
+        "getattr/globals/importlib with a computed name, or a string registry, could reach it.",
+        "List it in keep if it is loaded by name; otherwise delete it.",
+        "It is reported as uncertain precisely because the parse cannot tell."),
+    # Complete
+    "complete.license_missing": _e(
+        "No licence file",
+        "There is no LICENSE, LICENCE, COPYING or UNLICENSE file at the root.",
+        "Add a LICENSE file.",
+        "Licences kept only in a subfolder."),
+    "complete.license_undeclared": _e(
+        "Licence not declared",
+        "Packaging metadata exists but declares no licence.",
+        "Add license = \"...\" (or license-files) to [project].",
+        "Licences declared only by a build plugin."),
+    "complete.readme_missing": _e(
+        "No README",
+        "There is no README at the root.",
+        "Add a README.md that says what it is, how to install it and how to use it.",
+        "README kept under docs/ only."),
+    "complete.readme_short": _e(
+        "README too short",
+        "The README is under 200 bytes.",
+        "Describe what it does, how to install it and how to use it.",
+        "A README that only links to full documentation."),
+    "complete.readme_sections": _e(
+        "README lacks install or usage",
+        "A README of 200+ bytes with no install heading or no usage heading.",
+        "Add an Install heading and a Usage heading.",
+        "Headings worded differently from the words the check knows."),
+    "complete.ci_missing": _e(
+        "No CI",
+        "No CI configuration was found.",
+        "Add a CI workflow that runs the tests on each change.",
+        "CI configured outside the repository."),
+    "complete.metadata": _e(
+        "Incomplete metadata",
+        "pyproject.toml [project] lacks name, version (or dynamic) or requires-python.",
+        "Add the missing keys to [project].",
+        "None known."),
+    "complete.lockfile": _e(
+        "Application without a lockfile",
+        "The repo is an application (a Dockerfile, a __main__.py without scripts, or a web app object) and has no "
+        "lockfile.",
+        "Commit a lockfile (uv lock, poetry lock or pip-compile).",
+        "Libraries are never asked for one; an example app outside examples/ can make a library look like an app."),
+    "complete.env_example": _e(
+        "No .env.example",
+        "The code reads environment variables but there is no .env.example listing them.",
+        "Add a .env.example with every variable and a safe placeholder.",
+        "Libraries that read only optional, well-known variables (NO_COLOR, TERM)."),
+    "deps.declared_unused": _e(
+        "Declared but never imported",
+        "A runtime dependency nothing in the repo imports.",
+        "Remove it, or note why it is needed (a plugin or a runner).",
+        "Plugins and runners loaded by other tools; INFO, never scored."),
+    "check.crashed": _e(
+        "A check crashed",
+        "One of code-guardian's own checks raised on this file; the rest of the scan ran.",
+        "Report it at github.com/LuminariSoftwares/code-guardian/issues with the file if you can share it.",
+        "It is a code-guardian bug, never a finding about your code."),
+}
+
+
+def main(argv=None):
+    argv = sys.argv[1:] if argv is None else argv
+    if "--selftest" in argv:
+        from . import score
+        codes = {c for table in score.TABLES.values() for c, _ in table}
+        checks = [
+            ("covers_every_scored_code", codes <= set(CATALOGUE)),
+            ("four_fields", all(set(e) == {"title", "means", "fix", "false_positives"} for e in CATALOGUE.values())),
+            ("short_titles", all(len(e["title"]) <= 40 for e in CATALOGUE.values())),
+        ]
+        return summarize("catalogue", checks)
+    sys.stderr.write("usage: python -m code_guardian.catalogue --selftest\n")
+    return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

code_guardian/cli.py

@@ -0,0 +1,146 @@
+"""code-guardian command line.
+
+    code-guardian scan PATH [--json | --sarif | --markdown] [--goal FILE] [--explain] [--online] [--fail-on LEVEL]
+    code-guardian orphans PATH [--json] [--goal FILE] [--fail-on LEVEL]
+    code-guardian init [PATH] [--force]
+    code-guardian mcp                      # the MCP server on stdio (same as code-guardian-mcp)
+
+Exit codes: 0 nothing at or above --fail-on (default FAIL); 1 findings at or above it; 2 usage or parse error.
+scan gates on every scored finding (Safe, Works, Complete); orphans gates on the hygiene findings.
+"""
+
+import argparse
+import json
+import os
+import shutil
+import sys
+import tempfile
+
+from . import __version__, goal, outputs, report
+from .finding import summarize
+
+
+def _parser():
+    p = argparse.ArgumentParser(prog="code-guardian", description="Is this codebase safe to run, and is all of it used?")
+    p.add_argument("--version", action="version", version="code-guardian %s" % __version__)
+    sub = p.add_subparsers(dest="command")
+    fail_on = {"default": "FAIL", "type": str.upper, "choices": ["INFO", "WARN", "FAIL"],
+               "help": "exit 1 when any finding is at or above this level (default FAIL)"}
+    s = sub.add_parser("scan", help="Safe, Works and Complete scores, findings, egress inventory and orphan hygiene")
+    s.add_argument("path")
+    fmt = s.add_mutually_exclusive_group()
+    fmt.add_argument("--json", action="store_true", help="print the report as JSON")
+    fmt.add_argument("--sarif", action="store_true", help="print SARIF 2.1.0 (for GitHub code scanning)")
+    fmt.add_argument("--markdown", action="store_true", help="print a Markdown report (for a PR comment or job summary)")
+    s.add_argument("--goal", metavar="FILE", help="goal contract (default PATH/%s if present)" % goal.FILENAME)
+    s.add_argument("--explain", action="store_true", help="add a plain-English explanation from a local model")
+    s.add_argument("--online", action="store_true",
+                   help="ask PyPI whether unknown dependency names exist (network; off by default)")
+    s.add_argument("--fail-on", **fail_on)
+    o = sub.add_parser("orphans", help="code nothing reachable from the entry points uses")
+    o.add_argument("path")
+    o.add_argument("--json", action="store_true")
+    o.add_argument("--goal", metavar="FILE")
+    o.add_argument("--fail-on", **fail_on)
+    i = sub.add_parser("init", help="write a starter %s with the inferred entry points" % goal.FILENAME)
+    i.add_argument("path", nargs="?", default=".")
+    i.add_argument("--force", action="store_true", help="overwrite an existing goal file")
+    return p
+
+
+def init(path, force=False, out=print):
+    """Write PATH/code-guardian.goal.toml with the inferred entry points. --force replaces an existing file and keeps
+    its goal sentence, keep and exclude lists."""
+    root = report._root(path)
+    target = os.path.join(root, goal.FILENAME)
+    old = None
+    if os.path.exists(target):
+        if not force:
+            raise report.UsageError("%s already exists (use --force to overwrite)" % goal.FILENAME)
+        old = goal.load(target)
+    entries = report.orphans(root, infer=True)["entry_points"]
+    sentence = (old or {}).get("goal") or "Describe in one sentence what this project is for."
+    with open(target, "w", encoding="utf-8") as fh:
+        fh.write(goal.render(sentence, entries, (old or {}).get("keep", ()), (old or {}).get("exclude", ())))
+    out("wrote %s with %d inferred entry point(s):" % (goal.FILENAME, len(entries)))
+    for e in entries:
+        out("  " + e)
+    if not entries:
+        out("no entry points found: add them by hand as module:function")
+    return 0
+
+
+def main(argv=None):
+    argv = sys.argv[1:] if argv is None else argv
+    if argv[:1] == ["mcp"]:  # `code-guardian mcp` starts the same server as `code-guardian-mcp`
+        from . import mcp_server
+        return mcp_server.main(argv[1:])
+    if argv[:1] == ["--selftest"]:
+        return selftest()
+    args = _parser().parse_args(argv)
+    try:
+        if args.command == "scan":
+            rep = report.scan(args.path, args.goal, explain=args.explain, online=args.online)
+            if args.json:
+                sys.stdout.write(json.dumps(rep, indent=1) + "\n")
+            elif args.sarif:
+                sys.stdout.write(json.dumps(outputs.to_sarif(rep), indent=1) + "\n")
+            elif args.markdown:
+                sys.stdout.write(outputs.to_markdown(rep))
+            else:
+                sys.stdout.write(report.render(rep))
+            return report.exit_code(rep["findings"], args.fail_on)
+        if args.command == "orphans":
+            hyg = report.orphans(args.path, args.goal)
+            sys.stdout.write(json.dumps(hyg, indent=1) + "\n" if args.json else report.render_orphans(hyg))
+            return report.exit_code(hyg["findings"], args.fail_on)
+        if args.command == "init":
+            return init(args.path, args.force)
+    except (report.UsageError, goal.GoalError) as exc:
+        sys.stderr.write("code-guardian: %s\n" % exc)
+        return 2
+    _parser().print_help(sys.stderr)
+    return 2
+
+
+def selftest():
+    import contextlib
+    import io
+
+    tmp = tempfile.mkdtemp()
+    try:
+        os.makedirs(os.path.join(tmp, "app"))
+        with open(os.path.join(tmp, "app", "run.py"), "w", encoding="utf-8") as fh:
+            fh.write("import requests\ndef main():\n    requests.get('https://example.com', verify=False)\n"
+                     "if __name__ == '__main__':\n    main()\n")
+
+        def run(*argv):
+            out, err = io.StringIO(), io.StringIO()
+            with contextlib.redirect_stdout(out), contextlib.redirect_stderr(err):
+                try:
+                    code = main(list(argv))
+                except SystemExit as exc:
+                    code = exc.code
+            return code, out.getvalue()
+
+        scan_code, scan_json = run("scan", tmp, "--json")
+        init_code, _ = run("init", tmp)
+        again, _ = run("init", tmp)
+        forced, _ = run("init", tmp, "--force")
+        checks = [
+            ("scan_fail_exit_1", scan_code == 1 and json.loads(scan_json)["scores"]["safe"] == 75),
+            ("fail_on_case_insensitive", run("scan", tmp, "--fail-on", "fail")[0] == 1),
+            ("orphans_exit_0", run("orphans", tmp)[0] == 0),
+            ("usage_exit_2", run("scan")[0] == 2 and run("scan", os.path.join(tmp, "nope"))[0] == 2),
+            ("bad_level_exit_2", run("scan", tmp, "--fail-on", "LOUD")[0] == 2),
+            ("init", init_code == 0 and goal.load(os.path.join(tmp, goal.FILENAME))["entry_points"] == ["app.run:__main__"]),
+            ("init_no_overwrite", again == 2 and forced == 0),
+            ("bad_goal_exit_2", run("scan", tmp, "--goal", os.path.join(tmp, "missing.toml"))[0] == 2),
+        ]
+    finally:
+        shutil.rmtree(tmp, ignore_errors=True)
+    return summarize("cli", checks)
+
+
+if __name__ == "__main__":
+    sys.exit(main())