Guardana

🛡️ Guardana

Guardana is an open-source AI security verification tool for security and platform engineers. It checks code and model artifacts, live AI systems, and recorded runs. It reports what it found, what it could not verify, and what it could not check. It verifies outside the request path; it is not an inline guardrail, a general SAST or CVE scanner, or a compliance certification.

Quickstart · Features · Rule catalog · Docs · Status & limits · Current work · Changelog · Get involved

58 built-in security checks; add checks for your application. The count comes from the generated rule summary. Built-in artifact checks need no network. scan --reporter server://<url> sends results to a collector; active checks contact the target you choose. Guardana needs no account and has no automatic telemetry or phone-home.

Quickstart

uvx --from guardana-cli guardana scan .   # zero-install run (uv)
uv add guardana-cli                       # or: pip install guardana-cli

The command is guardana; the distribution is guardana-cli. An uncached uvx run or an install downloads the distribution. For a source checkout, clone and run uv sync as described in docs/install.md.

Start with an offline result:

# With uvx:
uvx --from guardana-cli guardana init --starter first-run

# After uv add guardana-cli:
uv run guardana init --starter first-run

# After pip install guardana-cli in an active environment:
guardana init --starter first-run

Its README walks through a failing scan, the fix, a saved run, and a check of your own. Once Guardana is installed, it needs no account, key, model, or network.

Scan the bundled vulnerable model directory in a clone of the repository for another example (pip, uv add and uvx installs do not contain examples/vulnerable-model):

$ uv run guardana scan examples/vulnerable-model

✖ [CRITICAL] guardana.supply_chain.pickle_opcode — Dangerous pickle opcode (arbitrary code on load)
    unpickling imports 1 non-allowlisted callable(s) (set 705e9da4c561): posix.system  (examples/vulnerable-model/model.pt)
✖ [HIGH] guardana.supply_chain.dependency_risk — Unsafe model/deserialization loader call
    torch.load without weights_only=True  (examples/vulnerable-model/load_model.py:3)
✖ [CRITICAL] guardana.supply_chain.remote_code_config — Model config requests custom-code execution on load
    '_attn_implementation_internal' names the Hub kernel repository 'attacker/kernel-repo', which transformers downloads and imports on load — a private field, so trust_remote_code=False does not stop it (CVE-2026-4372)  (examples/vulnerable-model/config.json)
…
▲ [MEDIUM] guardana.supply_chain.hallucinated_package — Import of unknown package (possible slopsquat lead)
    import 'torchutilz' isn't a known package or a declared dependency — declare it in requirements/pyproject, or verify it exists on PyPI  (examples/vulnerable-model/train.py:1)
…

12 finding(s); 19 rule(s) run, 0 skipped. 5 component(s) observed.

That run exits 1, so it can gate CI. To check your own work:

guardana scan path/to/your/project                      # static, offline, no model needed
guardana init                                           # write a guardana.yaml policy file
guardana scan . --profile guardana.yaml --format sarif  # SARIF 2.1.0 for GitHub code scanning

guardana probe --url http://localhost:11434 --model llama3 --preset ci --format json --output run.json
guardana diff accepted-run.json run.json   # 0 nothing worse at the policy's bars · 1 it is · 2 cannot tell

Choose a guide for your own project, a run your application recorded, or the application your users talk to. To add Guardana to an existing repository and pipeline, follow Adopt Guardana in your project.

For integration requirements, see feature and field availability and the compatibility matrix. Package availability identifies when an item first shipped; document schemas, extension_api and output_api have independent versions.

Every published distribution has signed, keyless build provenance verifiable with gh attestation verify, plus a PEP 740 attestation on PyPI.

What it checks

The generated rule summary counts 58 built-in rules: 19 artifact rules and 39 runtime rules. The runtime rules span live endpoints, live MCP servers, live A2A agents, seeded applications, and recorded traces. A single endpoint does not exercise all 39. Rules map to both editions of the OWASP LLM Top 10, the OWASP Top 10 for Agentic Applications, the OWASP MCP Top 10, OWASP ML Top 10, MITRE ATLAS v5.6.0, and NIST AI 100-2e2025. References include their edition.

The 19 static rules need no model or network. The generated rule catalog lists built-in rule ids, severities, surfaces, and framework mappings. guardana rules shows rules admitted in the current installation, including trusted third-party rules. See FEATURES.md for the capability overview and the generated detection limits for what each finding establishes.

How results gate a run

Guardana keeps four outcomes separate:

• findings: a check reached a negative verdict;
• unverified: it ran but could not decide;
• errors: it could not run;
• coverage shortfalls: required evidence was unavailable, or the scan observed a model file that no running rule examined.

Results that require judgment include an outcome, confidence, rationale, and evaluator identity. guardana calibrate measures evaluator confidence against labelled samples. An exhausted budget exits 6 and preserves its results. A comparison that cannot be made exits 2. Missing evidence is not reported as success.

Use it in CI and your application

Guardana verifies artifacts, deployed systems, and recorded evidence:

scan, probe, monitor, and analyze-trace can send findings to an optional collector with --reporter server://<url>. Other commands cover planning, capability inspection, configuration, baselines, run inspection, rule testing, and extension packs. See docs/index.md. Exit codes have nine documented meanings (0–8), tested against docs/exit-codes.md; CI does not need to parse console text.

GitHub Actions

# .github/workflows/ai-security.yml
name: AI security
on: [push, pull_request]
jobs:
  guardana:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      security-events: write   # to upload SARIF
    steps:
      - uses: actions/checkout@v7
      - uses: guardana/[email protected]   # moving tag → latest 1.0.x
        # with:
        #   args: --preset ci --baseline guardana-baseline.yaml

Both actions/checkout@v7 and guardana/[email protected] are moving tags. Replace them with full commit SHAs if your workflow requires pinned actions. The published Guardana Action pins the actions it calls by SHA; that does not pin these two references in your workflow. A pre-commit hook and templates for GitLab, Jenkins, and Azure DevOps are in docs/integrations.md.

Tests and Python

The same rules, policy, redaction, and gate work in tests (docs/usage-testing.md):

from guardana.adapters.langchain import langchain_target
from guardana.testing import assert_secure

def test_the_repository_ships_no_dangerous_artifact():
    assert_secure("models", preset="ci")

def test_the_agent_keeps_its_instructions_to_itself(chat_model):
    assert_secure(langchain_target(chat_model, system_prompt=SYSTEM), preset="ci")

To read a run as data instead of asserting on it, the supported guardana.core.verify API returns what scan and probe write, including failed and budget-stopped outcomes. Python callers must state plugin trust. Quality suites gate answer quality on team-supplied versioned datasets; see the quality-suite guide.

Before active testing

Probes send real requests and can cost money or trigger provider abuse detection. The default profile sets no request or cost ceiling. Set a budget before using a paid target, and prefer staging. Guardana sends tool calls to doubles, but the surrounding application can still act on a model response. Evidence may contain sensitive text and is redacted by default. guardana monitor re-runs active probes on a schedule. See docs/safe-testing.md, docs/privacy.md, and docs/profiles.md.

For example, put this budget in guardana.yaml:

budgets: {max_requests: 60, max_duration: 5m}

Plan first, then probe a staging URL:

guardana plan probe --url https://staging.example/v1 --model support-bot --profile guardana.yaml
guardana probe --url https://staging.example/v1 --model support-bot --profile guardana.yaml

A probe with missing coverage exits 2 (indeterminate), which is not a pass.

What Guardana observes in three systems

flowchart LR
  accTitle: How Guardana checks an AI system
  accDescr: Model and code artifacts go to guardana scan, a live endpoint, agent or MCP server to guardana probe or monitor, and a recorded agent run or the answers your application already gave to guardana analyze-trace or guardana grade. All of them run one rule engine, which writes a saved run with findings, unverified checks, errors and coverage shortfalls. The run gates the build, feeds guardana diff, and renders as SARIF, JSON, JUnit or text.
  classDef accent fill:#F0ECFF,stroke:#5B3DF5,color:#4A2FE0
  classDef cmd font-family:monospace
  subgraph IN [What you point it at]
    A[Model and<br>code artifacts]
    B[Endpoint, agent<br>or MCP server]
    C[Recorded run<br>or answers]
  end
  A --> S([guardana scan]):::cmd
  B --> P([guardana probe<br>or monitor]):::cmd
  C --> T([guardana<br>analyze-trace<br>or grade]):::cmd
  S ==> E[One rule engine<br>rules · evaluators · profile]:::accent
  P ==> E
  T ==> E
  E ==> R[(Saved run<br>findings · unverified<br>errors · shortfalls)]
  subgraph OUT [What you get]
    G[Gate verdict<br>and exit code]
    D([guardana diff]):::cmd
    F[SARIF · JSON<br>JUnit · text]
  end
  R --> G
  R --> D
  R --> F

Extend it for your application

The 58 built-ins cover shared risks. Installed packages have six entry-point groups: rules, evaluators, targets, taxonomies, renderers, and reporters. Rules express checks in YAML or Python; evaluators grade replies (configuration supports llm_judge through an OpenAI-compatible endpoint and the optional guard classifier); targets connect through locator schemes; taxonomies add control sets; renderers add formats; reporters add destinations. See docs/writing-rules.md, docs/outputs.md, and docs/extending.md.

A profile (guardana.yaml) configures a run. A finding is a result format. A security contract declares policy for one application. None is an entry-point group.

One pack flow is: install guardana-reference-pack from PyPI with pip install guardana-cli guardana-reference-pack; admit it with --plugins allowlist --allow-plugin guardana-reference-pack or plugins: in a profile; select its rules in guardana.yaml; run guardana probe. examples/reference_pack includes sampled rules, a target, an evaluator, a taxonomy, a renderer and a reporter. The conformance kit checks that an extension keeps its contract.

By default, Guardana loads only its own distributions. It refuses an installed third-party pack before importing it and records the refusal as an error. Under the default gate, a run with a refused pack is indeterminate, even if that run did not select its rules. guardana doctor shows what would load. Admitted Python packs run with your privileges; see SECURITY.md.

examples/custom_rule/ is a working third-party package. guardana new-rule scaffolds a rule. The guardana-core library supports embedding the engine without the CLI. See docs/architecture.md and docs/product-status.md. The compatibility policy is in docs/compatibility.md.

Maturity and limits

The engine and built-in rules, scan, diff, supported Python verification API and extension API are stable under docs/compatibility.md. probe, grade, analyze-trace, monitor, quality suites with deterministic assessors and the optional collector are beta, and judge-graded suites are experimental; read docs/product-status.md before using Guardana as a security gate.

Guardana's agent harness tests a model with Guardana's scripted tools; it does not exercise your agent's own framework and tools. Trace analysis checks an execution your application recorded. monitor samples by running active checks; it does not inspect production traffic. A scan of a path with no file to read is indeterminate rather than a pass, but a scan cannot tell whether the files it read are the ones you meant to ship; a release preset needs rules selected for the target's capabilities. The current checks cover text, not image, PDF, audio, or document carriers. Provider compatibility and judge-graded verdicts need validation for your deployment.

Where Guardana fits

A run records what was checked, what could not be checked, and the sample used. This distinguishes fewer findings from less coverage and prevents an invalid comparison from appearing as no change.

Central monitoring — self-hosted

The collector is optional. Local and CI verification do not depend on it. For shared visibility, runs can send normalized findings to self-hosted guardana-server, backed by PostgreSQL with an opt-in dashboard. The collector's HTTP API stores and serves results and does not start scans or probes. /openapi.json describes its routes, ingest and read key permissions, and refusals.

Maturity: beta. Finding routes require scoped API keys. Projects cannot read each other's data, and keys can be pinned to an environment. Findings have audited lifecycle states and expiring waivers. Operators control retention and deletion. The dashboard uses a read-scoped session; it has no human identities or RBAC. docs/usage-collector.md · docs/deployment.md

The engine and built-in rules are Apache-2.0. See the project principles and current work.

Documentation

• docs/index.md — documentation map
• docs/product-status.md — maturity and known limits
• docs/how-it-works.md — product overview
• docs/install.md · docs/usage-init.md · docs/profiles.md · docs/exit-codes.md
• docs/usage-suites.md · docs/python-api.md — quality suites and supported Python API
• docs/threat-model.md · docs/privacy.md · docs/safe-testing.md
• Current work · Release milestones · CHANGELOG.md

Security

Report suspected vulnerabilities privately through SECURITY.md, never public issues. Review third-party Python packs before admitting them; the security policy explains plugin trust and supported versions.

Related project: Guardana Control

Guardana Control is a separate, independent open-source project. It sits in the request path of an AI agent's MCP tool calls: it decides each call, enforces the decision, and records evidence. It is alpha; its own README says not to deploy it as a security boundary. Guardana verifies from outside any request path, before and between releases. Neither project needs the other.

Get involved

• Try it in about ten minutes and tell us where you got stuck in a first-run session.
• Bring your team's LLM, RAG or MCP application as a pilot. Start in GitHub Discussions or email [email protected].
• Write your own pack or check. See docs/extending.md and examples/.
• Star the repository or watch releases to follow new releases.

See CONTRIBUTING.md. New rules need a framework mapping and fixtures.

[email protected] · karauda.com/contact · guardana.dev · github.com/guardana

License

Apache License 2.0 — see LICENSE. Use it, ship it, build on it.