exit

meaning

0

nothing at or above --fail-on (default FAIL)

1

findings at or above it

2

usage error, a missing PATH, or a bad goal file

code

what it looks for

level

weight

secret.key

API-key shapes (the privacy workflow's built-in list: sk- (which covers Anthropic's sk-ant-), sk-or-, tvly-, ghp_, github_pat_, nvapi-, gsk_, AIza; plus AWS access key IDs AKIA/ASIA + 16, Stripe sk_live_/rk_live_, Slack xox[abprs]-, Hugging Face hf_ + 30 letters), a 40-character AWS secret key assigned to a name containing aws and secret, private-key blocks, password = "<literal>" (also api_key, secret, access_token…), and any *_KEY / *_TOKEN name holding a long, high-entropy literal. One finding per line. Values are never printed; values that call themselves fake (mock, dummy, example…) are skipped

FAIL

40

secret.key

a Stripe test-mode key (sk_test_)

INFO

0

exec.dynamic

eval, exec, compile on non-literal input; __import__ with a variable

WARN

10

exec.dynamic

…when eval or exec runs text from input(), sys.argv, request data, os.environ or a network read (the exec.shell taint rule, one function deep; exec(compile(...)) counts at the exec): "runs code typed by the user"

FAIL

30

exec.shell

os.system, os.popen, subprocess.*(..., shell=True)

WARN

10

exec.shell

…when the command is built from input(), os.environ, sys.argv or a network read

FAIL

30

deser.unsafe

pickle.load(s), marshal.loads, yaml.load without SafeLoader, torch.load without weights_only=True

WARN

10

net.egress

every URL and IP literal plus every urllib/requests/httpx/socket.connect call site: the egress inventory

INFO

0

net.egress

a publicly routable IP, or plain http/ws/ftp to a public name or to a host chosen at runtime

WARN

2

net.bind_all

binding 0.0.0.0 or ::

WARN

5

tls.off

verify=False, ssl._create_unverified_context, CERT_NONE, check_hostname = False, hard-coded

FAIL

25

tls.off

…only under an if on a function parameter: the caller opts out (how httpx implements verify=False)

WARN

10

install.hook

setup.py cmdclass or install-command subclasses, package.json preinstall/install/postinstall, an in-tree build backend

WARN

15

obfuscation

exec/eval of base64/zlib/marshal/hex-decoded data

FAIL

40

obfuscation

base64 or hex blobs of 200+ characters, high-entropy string literals

WARN

10

fs.outside

writes, deletes and moves aimed at absolute paths, ~, or .. escapes

WARN

3

deps.unpinned

dependencies with no pin or upper bound (pyproject.toml, setup.py, setup.cfg, requirements*.txt, package.json)

INFO

0

code

what it looks for

level

weight

supply.unknown_package

offline (default): a declared dependency or an unresolved import that is not in the bundled list of known packages; run with --online to check it exists

INFO

0

supply.unknown_package

--online: PyPI has no such project (likely invented by an AI assistant; anyone could register the name)

FAIL

40

supply.unknown_package

--online: the project's first release is under 90 days old, or it has only one release

WARN

10

supply.lookalike

one or two edits (insert, delete, change, swap) away from a known package without being it; two edits only for names of 8+ characters, none under 5

WARN

15

code

what it looks for

level

weight

works.syntax

a .py file that ast.parse rejects (Python 2 code, a typo); it still gets the secret scan

FAIL

30

works.syntax

…when the project's requires-python is newer than the Python running code-guardian (it cannot tell)

INFO

0

works.import_unresolved

an absolute import that is not in the standard library, not a module or package in the repo, and not a declared dependency

WARN

10

works.relative_missing

a relative import (from .x import y) that points at a module the repo does not have

FAIL

25

works.tests_missing

no test files at all (tests/, test_*.py, *_test.py, tests.py, conftest.py)

WARN

15

works.test_no_assert

test functions with no assert, no pytest.raises/warns, no self.assert* and no call to a local helper that asserts; once per file, with the count

WARN

5

works.entry_missing

a [project.scripts] (or setup.cfg console script) target module:function whose module or function is not in the tree

FAIL

30

orphan.dead

dead code from the hygiene section (below), folded in at a low weight, only when entry points exist

WARN

3

code

what it looks for

level

weight

complete.license_missing

no LICENSE, LICENCE, COPYING or UNLICENSE file at the root

WARN

20

complete.license_undeclared

packaging metadata ([project], Poetry, setup.cfg, setup()) declares no licence (license, license-files or a License :: classifier)

WARN

5

complete.readme_missing

no README at the root

WARN

20

complete.readme_short

the README is under 200 bytes

WARN

10

complete.readme_sections

a README of 200+ bytes with no install heading (install, setup, getting started, quick start) or no usage heading (usage, examples, tutorial, run, CLI…)

WARN

5

complete.ci_missing

no CI configuration (.github/workflows/, .gitlab-ci.yml, .circleci/, azure-pipelines.yml, .travis.yml, Jenkinsfile…)

WARN

10

complete.metadata

pyproject.toml [project] without name, version (or dynamic) or requires-python

WARN

10

complete.lockfile

an application with no lockfile (uv.lock, poetry.lock, Pipfile.lock, pdm.lock, pixi.lock, requirements.lock, or a fully pinned requirements.txt)

WARN

10

complete.env_example

the code reads environment variables (os.environ, os.getenv, dotenv) and there is no .env.example (or .env.sample, .env.template, example.env)

WARN

10

deps.declared_unused

a runtime dependency that nothing in the repo imports (runners, linters, types-* and pytest-* plugins are skipped)

INFO

0

flag

prints

(none)

the text report shown above

--json

the full report (shape above)

--sarif

SARIF 2.1.0 for GitHub code scanning: one rule per check code (title, meaning, fix and false-positive notes from the catalogue below; Safe rules carry security-severity), one result per finding. Repo-level findings (no file) are attached to the root manifest or README, because code scanning needs a file for every result. Validated in CI against the official schema

--markdown

a Markdown report for a pull-request comment or a job summary

code

dimension

what it means

how to fix it

false positives

check.crashed

Safe

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.

deps.unpinned

Safe

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.

deser.unsafe

Safe

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.

exec.dynamic

Safe

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

Safe

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.

fs.outside

Safe

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.

install.hook

Safe

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.

net.bind_all

Safe

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.

net.egress

Safe

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.

obfuscation

Safe

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.

secret.key

Safe

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.

supply.lookalike

Safe

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.

supply.unknown_package

Safe

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.

tls.off

Safe

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.

orphan.dead

Works

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

Works

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

Works

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.

works.entry_missing

Works

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.

works.import_unresolved

Works

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

Works

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.syntax

Works

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.test_no_assert

Works

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.tests_missing

Works

There are no test files at all.

Add a tests/ folder with at least one test per entry point.

Tests kept in another repository.

complete.ci_missing

Complete

No CI configuration was found.

Add a CI workflow that runs the tests on each change.

CI configured outside the repository.

complete.env_example

Complete

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).

complete.license_missing

Complete

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

Complete

Packaging metadata exists but declares no licence.

Add license = "..." (or license-files) to [project].

Licences declared only by a build plugin.

complete.lockfile

Complete

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.metadata

Complete

pyproject.toml [project] lacks name, version (or dynamic) or requires-python.

Add the missing keys to [project].

None known.

complete.readme_missing

Complete

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_sections

Complete

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.readme_short

Complete

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.

deps.declared_unused

Complete

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.

code

meaning

level

orphan.dead

nothing reachable uses it

WARN

orphan.test_only

only tests reach it

INFO

orphan.uncertain

getattr/globals()/importlib with a computed name could reach it, or its name is a string in reachable code (a registry)

INFO

tool

does

openWorldHint

scan

the full report for path (+ optional goal, fail_on; the reply carries exit_code)

false

orphans

the hygiene section for path

false

explain

scan plus the model explanation

true