controlloop 0.1.0__tar.gz

controlloop-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+.coverage
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.venv/
+__pycache__/
+dist/
+dist-binary/
+build-binary/
+*.egg-info/
+*.py[cod]

controlloop-0.1.0/LICENSE

@@ -0,0 +1,191 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2026 ControlLoop
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

controlloop-0.1.0/PKG-INFO

@@ -0,0 +1,427 @@
+Metadata-Version: 2.5
+Name: controlloop
+Version: 0.1.0
+Summary: Local-first security scanner and deterministic CI gate for AI agents
+License-Expression: Apache-2.0
+License-File: LICENSE
+Requires-Python: <3.13,>=3.12
+Requires-Dist: pathspec<2,>=1.1.1
+Requires-Dist: pydantic<3,>=2.12
+Requires-Dist: python-hcl2>=8.1.2
+Requires-Dist: pyyaml>=6.0.3
+Requires-Dist: typer<1,>=0.21
+Description-Content-Type: text/markdown
+
+# ControlLoop CLI
+
+**A local-first scanner and deterministic CI gate for what your AI agents can
+actually do.**
+
+An agent's real authority is spread across an agent card, an MCP config, an
+OpenAPI spec, an IAM policy -- and, for most agents, the framework code
+itself: a CrewAI crew, a LangGraph graph, an OpenAI Agents SDK handoff
+chain. No single file tells you that adding one
+skill just gave it the ability to move money. ControlLoop reads those files,
+builds one graph of the agent's capabilities, compares it to the state you
+approved, and fails your build when the agent's authority grows past the
+ceiling you declared.
+
+It runs entirely on your machine. It never executes your code, never starts
+your MCP servers, never contacts a declared endpoint, and never sends your
+source anywhere.
+
+> **Development preview.** `init`, `bom`, `diff`, `scan`, `gate`, `rules`, and
+> `example` all work
+> and are covered by tests. There is no published release yet — no PyPI
+> package, no Homebrew tap, no container image, no tagged version. Install
+> from source as below. See [What is not built yet](#what-is-not-built-yet).
+
+---
+
+## Why use it
+
+- **Catch capability growth in review, not after.** A pull request that adds
+  a bulk-refund tool is blocked with the reason, the path, and a retained
+  evidence artifact — before it merges.
+- **Declare a ceiling and have it hold.** Pattern rules only catch what
+  someone anticipated. A capability ceiling blocks authority you never
+  imagined, through routes no rule matches.
+- **Deterministic.** Same inputs, same pinned versions, same digest, same
+  verdict. No model decides whether your build passes.
+- **Nothing protected leaves.** Source, prompts, credentials, environment
+  values, and customer data never appear in output, logs, errors, identity
+  material, or artifacts.
+- **Free and local.** Core scanning works with the network disabled.
+
+## Install and first run
+
+Requires **Python 3.12**, [**uv**](https://docs.astral.sh/uv/), and Git.
+
+```bash
+cd cli
+uv sync --locked --all-groups
+uv run controlloop --version
+```
+
+```
+ControlLoop 0.1.0
+Supported OASF versions: none yet
+Rule pack: controlloop-community 0.2.0 (10 rules)
+```
+
+Point it at a repository containing an agent:
+
+```bash
+uv run controlloop scan /path/to/your/agent-repo
+```
+
+Nothing to try it on? The public
+[reference agent](https://github.com/danny-tijerina2/controlloop-reference-agent)
+is a realistic, deliberately imperfect agent built for exactly this:
+
+```bash
+git clone https://github.com/danny-tijerina2/controlloop-reference-agent
+uv run controlloop scan controlloop-reference-agent/scenarios/order-support-agent
+```
+
+## The commands
+
+New here? Run `controlloop example` — it prints a five-step walkthrough and
+points at the [Example walkthrough](../docs/guides/example-walkthrough.md)
+guide.
+
+| Command | Use it to |
+| --- | --- |
+| `example` | Print a guided walkthrough of how ControlLoop works |
+| `rules` | List the rule pack in use and what each rule looks for |
+| [`init`](#init) | Draft a `controlloop.yaml` from what's actually in the repo |
+| [`bom`](#bom) | Generate or validate the capability graph (ACBOM) |
+| [`diff`](#diff) | See what changed against a baseline |
+| [`scan`](#scan) | Full report for a human: graph, policy, findings |
+| [`gate`](#gate) | One verdict and one exit code, for CI |
+
+`scan` is what you run at your desk. `gate` is what you run in CI. Both do
+the same analysis; `gate` never prompts, always writes an evidence artifact,
+and returns a verdict designed to be acted on by a machine.
+
+### `init`
+
+```bash
+uv run controlloop init [REPOSITORY] [--dry-run]
+```
+
+Discovers candidate agents and writes a reviewable `controlloop.yaml`. Every
+field is present even where ControlLoop could not determine a value — those
+are marked `TODO` with a comment saying what to supply. It evaluates no
+policy and enforces nothing.
+
+`--dry-run` prints the draft instead of writing it. Real output:
+
+```
+# controlloop.yaml
+# ControlLoop security manifest -- generated by `controlloop init`.
+...
+# Manifest schema version 1.1.0.
+
+schema_version: "1.1.0"
+
+# TODO: owner
+# ControlLoop cannot determine who is accountable for this
+# repository's agents. Replace the placeholder below with an
+# identifier for the responsible team or individual (for
+# example: "platform-security" or "jane.doe").
+owner: "TODO-owner"
+
+trust_boundaries:
+  # Discovered candidate agents (from repository discovery):
+  #   - invoice-agent  (tools observed: Send an invoice)
+  - name: "TODO-trust-boundary-name"
+```
+
+### `bom`
+
+```bash
+uv run controlloop bom [REPOSITORY] [-o PATH] [--validate] [--format acbom|cyclonedx]
+```
+
+Builds the **Agent Capability Bill of Materials** — the canonical graph of
+agents, tools, resources, identities, and permissions, with evidence for
+every node and edge.
+
+```bash
+uv run controlloop bom ./agent-repo -o acbom.json
+uv run controlloop bom acbom.json --validate
+```
+
+```
+✓ VALID  acbom.json is a valid ACBOM
+```
+
+`--validate` checks an existing file against this reader's own schema
+version. Use `--format cyclonedx` for a CycloneDX projection.
+
+### `diff`
+
+```bash
+uv run controlloop diff [FIRST] [SECOND] [--baseline REF] [--format text|json]
+```
+
+- `diff <repo>` — compare the repository against its resolved baseline
+  (a committed `.controlloop/baseline.json`, else the merge-base of your
+  default branch).
+- `diff <baseline.json> <current.json>` — compare two ACBOM files directly.
+- `--baseline` — an explicit baseline file *or* git revision.
+
+```
+• BASELINE   committed baseline: .controlloop/baseline.json
+• SCOPE      effective authority only -- node and edge changes were not evaluated
+
+• ADDED    capability  clp:agent:sha256:2321fe51…  invokes  clp:tool:sha256:ccc68b72…
+
+1 change: 1 added
+```
+
+### `scan`
+
+```bash
+uv run controlloop scan [REPOSITORY] [--format text|json|sarif]
+```
+
+Discovery, graph, baseline comparison, and all ten policy rules, rendered as
+a full report. `--format json` gives you the complete report;
+`--format sarif` gives a SARIF 2.1.0 log for code-scanning tools.
+
+### `gate`
+
+```bash
+uv run controlloop gate [REPOSITORY] \
+  [--evidence-path PATH] [--sarif-path PATH] \
+  [--default-branch NAME] [--format text|json|sarif]
+```
+
+The CI form. Returns a four-state verdict (see
+[Reading the output](#reading-the-output)) and **always** writes an evidence
+artifact — including on a failing run, which is exactly when you need it.
+
+- `--evidence-path` — where the artifact goes (default `evidence.json`).
+  The parent directory must already exist.
+- `--sarif-path` — additionally write a SARIF log, carrying the blast-radius
+  statement as `runs[0].properties.controlloop.blastRadius`.
+- `--default-branch` — override which branch the merge-base baseline is taken
+  from, for CI checkouts where `origin/HEAD` is unset.
+
+`gate` needs real git history for an automatic baseline, so check out with
+`fetch-depth: 0`.
+
+## Reading the output
+
+Here is a real passing run against the reference agent:
+
+```
+! WORST REACHABLE  financial-action: widgetworks-order-support-agent can invokes
+  Issue a refund
+
+✓ PASSED
+
+• material change: not evaluated
+
+! MEDIUM  policy.undeclared-tools: Tool 'Look up an order' is reachable but not
+  declared in controlloop.yaml.
+    at agent-card.json
+
+Suppressions: none declared
+```
+
+Exit code `0`.
+
+**1. The blast-radius line comes first.** `WORST REACHABLE` is the single
+worst thing this agent can do *right now* — not what changed. It is the line
+you forward to your manager. Here: this agent can take a `financial-action`
+by invoking `Issue a refund`. If nothing is classified, it reads
+`• no material capability is reachable`.
+
+**2. The verdict.** `gate` returns one of four:
+
+| Verdict | Exit | Meaning |
+| --- | --- | --- |
+| `✓ PASSED` | 0 | Nothing blocking, nothing warned |
+| `! PASSED WITH WARNINGS` | 0 | Findings below the blocking threshold |
+| `! REVIEW REQUIRED` | 3 | Analysis was incomplete and enforcement is set to fail |
+| `✕ DEPLOYMENT BLOCKED` | 1 | A blocking finding |
+
+A report can additionally show `• NOT EVALUATED`, meaning no policy was
+evaluated at all — which is not the same as evaluating and finding nothing.
+
+Note the glyphs: `PASSED WITH WARNINGS` uses `!`, not `✓`. Every state is
+distinguishable by symbol and by word, never by colour alone.
+
+**3. Material change** — what changed against the baseline, by class.
+`not evaluated` means no comparison was possible, which is different from
+"compared and found nothing" (`• no material capability change`). ControlLoop
+never reports an unmade comparison as a clean one.
+
+**4. Findings.** Each carries a severity glyph and label (`✕ HIGH`,
+`! MEDIUM`), the rule ID, a plain-language message, and the evidence path.
+Symbols and words both, never colour alone.
+
+**5. Suppressions** are always listed, never hidden.
+
+### A blocked run
+
+```
+! WORST REACHABLE  destructive-action: widgetworks-order-support-agent can
+  invokes Bulk refund orders
+
+✕ DEPLOYMENT BLOCKED
+
+✕ HIGH    policy.destructive-or-financial-action: Agent gained new direct
+  invokes access to 'Bulk refund orders', classified as destructive-action and
+  financial-action.
+    at agent-card.json
+
+Completeness enforcement: warn (default)
+Evidence: evidence.json
+```
+
+Exit code `1`. Two things to notice:
+
+- The blast radius **got worse** — `financial-action` became
+  `destructive-action`. The agent's worst case degraded, and that is the
+  first thing the report says.
+- The finding says **"gained new"**. It is not objecting to refunds existing;
+  it is objecting to authority this change *introduces* against the approved
+  baseline. In `--format json` that appears as `"change_state": "added"`.
+
+### In JSON
+
+```json
+{
+  "rule_id": "policy.undeclared-tools",
+  "severity": "medium",
+  "confidence": "high",
+  "message": "Tool 'Look up an order' is reachable but not declared in controlloop.yaml.",
+  "change_state": "not-compared",
+  "remediation": "Declare this tool in controlloop.yaml ... or remove the agent's access to it if it was not intentional.",
+  "documentation_url": "https://docs.controlloop.ai/reference/policy-rules#undeclared-tools"
+}
+```
+
+Every finding carries its own `remediation` and a stable `documentation_url`.
+
+### Exit codes
+
+| Code | Name | Meaning |
+| --- | --- | --- |
+| 0 | `PASS` | No blocking finding |
+| 1 | `POLICY_FAIL` | A blocking finding |
+| 2 | `INVALID_INPUT` | Bad manifest, bad path, unreadable ACBOM |
+| 3 | `INCOMPLETE_ANALYSIS` | Analysis incomplete and enforcement set to fail (`REVIEW REQUIRED`) |
+| 4 | `ENTITLEMENT` | Reserved |
+| 5 | `INTERNAL_ERROR` | A bug — please report it |
+
+## Telling ControlLoop what your tools do
+
+**This is the step people miss.** Discovery reads your agent card and your
+OpenAPI spec, but nothing in a repository states that issuing a refund moves
+money. Without that, every capability is unclassified and every scan reports
+`no material capability is reachable`.
+
+Declare it in `controlloop.yaml`:
+
+```yaml
+schema_version: "1.1.0"
+owner: support-eng
+
+tool_capabilities:
+  - tool: Issue a refund        # the DISCOVERED tool name, not its id
+    financial_action: true
+    read_only: false
+    sensitivity: confidential
+  - tool: Purge ticket history
+    destructive: true
+```
+
+Match the **name discovery found**, which for an A2A skill is its card
+`name`, not its `id` — `Issue a refund`, not `issue-refund`. Run
+`controlloop bom` and read the node names if you are unsure; a declaration
+naming a tool that does not exist is reported, not silently ignored.
+
+Every boolean also accepts `"unknown"`, which the taxonomy ranks **worst of
+all**. An unknown risk is never treated as safer than a known one.
+
+## Declaring a ceiling
+
+The ceiling is the part that catches what nobody anticipated:
+
+```yaml
+ceilings:
+  - agent: widgetworks-order-support-agent
+    prohibited_resources:
+      - customer-payment-methods
+    prohibited_delegation_targets:
+      - unapproved-agent
+```
+
+Any reachable capability that breaches this blocks the gate — even with every
+pattern rule suppressed. A capability-ceiling breach **cannot** be suppressed.
+
+## In CI
+
+```yaml
+- uses: actions/checkout@v7.0.1
+  with:
+    fetch-depth: 0          # gate needs real history for a baseline
+- uses: danny-tijerina2/controlloop@<ref>
+  with:
+    path: ${{ github.workspace }}
+```
+
+The action runs `gate`, fails the check on a blocking verdict, uploads SARIF,
+and writes a check summary. See
+[the GitHub Action reference](../docs/reference/github-action.md). A
+[pre-commit hook](../docs/reference/pre-commit-hook.md) is also available.
+
+## What is not built yet
+
+Stated plainly, so you can plan:
+
+- **No published release.** No PyPI package, Homebrew tap, container image, or
+  tagged version. Source install only.
+- **No Team tier.** Private-repository gates, shared policy bundles, history,
+  attestations, dashboards, and billing do not exist.
+- **No runtime protection.** ControlLoop analyzes repositories. It does not
+  intercept, sandbox, or kill a running agent.
+- **Windows is unsupported.**
+- **Committed baselines carry no graph**, so `scan`/`gate` report
+  `material change: not evaluated` against one. Only the merge-base path
+  computes a material change summary.
+
+## Learn more
+
+- [CLI reference](../docs/reference/cli.md) — every command and flag
+- [Terminal report format](../docs/reference/terminal-report-format.md)
+- [Manifest schema](../docs/reference/manifest-schema.md)
+- [Capability ceiling](../docs/reference/capability-ceiling.md)
+- [Policy rules](../docs/reference/policy-rules.md) — all ten
+- [Material capability taxonomy](../docs/reference/material-capability-taxonomy.md)
+- [Privacy, security, and limitations](../docs/reference/privacy-security.md)
+
+---
+
+## For maintainers
+
+The lockfile is authoritative. Do not install unpinned project dependencies
+outside `uv`.
+
+```bash
+uv sync --locked --all-groups
+uv run ruff format --check .
+uv run ruff check .
+uv run mypy
+uv run pytest
+uv build
+```
+
+`uv run pytest` takes roughly two to three minutes locally, including real
+PyInstaller builds and a wall-clock performance benchmark that is sensitive
+to machine load.