stoa-agent-risk 0.1.0__tar.gz

stoa_agent_risk-0.1.0/LICENSE

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

stoa_agent_risk-0.1.0/PKG-INFO

@@ -0,0 +1,253 @@
+Metadata-Version: 2.4
+Name: stoa-agent-risk
+Version: 0.1.0
+Summary: Local-first AI agent inventory and risk scanner: finds agent candidates with evidence, maps capabilities and integrations, and gates newly introduced high-confidence critical risks.
+Author-email: Ved Upadhyay <iamved05@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 Stoa contributors
+        
+        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.
+        
+Project-URL: Homepage, https://stoa-features.vercel.app
+Project-URL: Repository, https://github.com/iamved/stoa-agent-risk
+Project-URL: Issues, https://github.com/iamved/stoa-agent-risk/issues
+Project-URL: Documentation, https://github.com/iamved/stoa-agent-risk#readme
+Keywords: ai-agents,security,static-analysis,llm,sast
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pathspec>=0.11
+Requires-Dist: tomli>=2.0; python_version < "3.11"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4; extra == "dev"
+Dynamic: license-file
+
+# Stoa
+
+**A local-first AI agent inventory and risk scanner** that identifies agent
+candidates with supporting evidence, maps their capabilities and integrations,
+and prevents newly introduced high-confidence critical risks from entering
+the codebase.
+
+Stoa scans Python, JavaScript, and TypeScript repositories statically — no
+runtime hooks, no uploads, no accounts.
+
+## What Stoa does
+
+- **Discovers likely AI agents** (LangChain, LangGraph, CrewAI, AutoGen,
+  LlamaIndex, OpenAI Agents SDK, PydanticAI, Bedrock Agents, Semantic Kernel,
+  LiteLLM, and raw provider calls) using weighted evidence, and shows exactly
+  *why* each candidate was detected.
+- **Maps providers, frameworks, integrations, and capabilities** — e.g. an
+  agent candidate with payment access, database reads, and Slack messaging.
+- **Detects high-confidence risks**: hardcoded credentials, hardcoded
+  passwords, interpolated SQL, swallowed exceptions, insecure HTTP, missing
+  request timeouts, and control-review prompts.
+- **Produces local reports**: a manager-friendly self-contained HTML report
+  and a deterministic, versioned JSON registry.
+- **Gates only newly introduced critical findings by default** — existing
+  debt never blocks an unrelated pull request.
+
+Stoa reports *candidates* and *evidence*, not certainties. A "control not
+observed" prompt is a review nudge, not a proven vulnerability.
+
+## Quick start
+
+```bash
+pipx install stoa-agent-risk
+cd my-repository
+stoa scan .
+open stoa-report.html
+```
+
+`stoa scan .` writes `stoa-report.html` and `stoa-registry.json` and exits 0
+(report-only) unless a gate is configured. The JSON is designed to be read by
+coding assistants too:
+
+```bash
+stoa scan . --json stoa-registry.json
+```
+
+## GitHub Actions
+
+```bash
+stoa init github
+```
+
+This creates (without overwriting existing files — use `--force` to
+overwrite):
+
+- `.github/workflows/stoa.yml` — full-history checkout, pinned Stoa install,
+  full-repository scan, diff against the PR base branch, GitHub annotations,
+  a job summary, uploaded HTML/JSON artifacts, and a gate that fails **only**
+  when the PR introduces a new high-confidence critical finding.
+- `.stoaignore` — gitignore-style path exclusions.
+- `stoa.toml` — configuration with documented defaults.
+
+## CLI
+
+```bash
+stoa scan [PATH]
+  --html PATH               HTML report (default stoa-report.html)
+  --json PATH               JSON registry (default stoa-registry.json)
+  --base GIT_REF            enable diff-aware behavior (e.g. origin/main)
+  --strict                  fail on all unsuppressed high-confidence criticals
+  --fail-on {none,high,critical}
+  --fail-on-new {none,high,critical}   applies with --base
+  --github-annotations      emit ::error/::warning workflow commands
+  --summary-file PATH       write a GitHub job-summary Markdown file
+  --config PATH             explicit stoa.toml
+  --no-git                  skip git metadata
+  --include / --exclude     extra path patterns (repeatable)
+  --verbose / --quiet
+```
+
+Exit codes: `0` gate passed · `1` gate failed · `2` invalid arguments or
+configuration · `3` scanner execution error.
+
+Only high-confidence findings from gate-eligible rules (SEC001, SEC002) can
+fail a scan; SQL-interpolation, network, and review-prompt rules report but
+never gate, because static regex analysis cannot prove exploitability.
+
+## Suppression
+
+Inline, on the same or preceding line, always with explicit rule IDs:
+
+```python
+# stoa: ignore[SEC003] trusted identifier from internal enum
+query = f"SELECT * FROM {table_name}"
+```
+
+```javascript
+const endpoint = "http://staging.internal.corp"; // stoa: ignore[NET001]
+```
+
+File-wide:
+
+```python
+# stoa: ignore-file[CTRL001,CTRL002]
+```
+
+Suppressed findings are counted and shown in reports — never silently
+discarded. There is no blanket `ignore-all`.
+
+## Configuration
+
+`stoa.toml` in the repository root (all values shown are defaults):
+
+```toml
+fail_on = "none"          # gate on all findings at/above this severity
+fail_on_new = "critical"  # gate on newly introduced findings (with --base)
+max_file_bytes = 1000000
+follow_symlinks = false
+respect_gitignore = true
+
+ignore_paths = [          # merged with built-in defaults (node_modules, dist, …)
+  "tests/snapshots/**",
+]
+
+[severity]                # per-rule severity overrides
+NET001 = "info"
+
+[rules]                   # per-rule enable/disable
+CTRL003 = false
+```
+
+`.stoaignore` uses gitignore syntax for path exclusions. Tests and fixtures
+are *not* ignored by default — secret scanning is still useful there — but
+they are downweighted for agent detection and placeholder-secret heuristics
+apply.
+
+## Rules
+
+| Rule | Title | Default severity | Gates? |
+|---|---|---|---|
+| SEC001 | Possible hardcoded API credential | critical | yes (high confidence only) |
+| SEC002 | Possible hardcoded password | high (critical at high confidence) | yes (high confidence only) |
+| SEC003 | Interpolated SQL statement | high | no |
+| REL001 | Swallowed exception | medium | no |
+| NET001 | Insecure non-local HTTP endpoint | medium | no |
+| NET002 | Request timeout not observed | medium | no |
+| CTRL001–003 | Auth / validation / rate-limit control not observed | info | never |
+
+## Security model
+
+- **Local-first.** No source code is uploaded anywhere; Stoa makes no network
+  calls and collects no telemetry.
+- **Secrets are redacted before serialization.** A detected credential is
+  replaced with `prefix…[REDACTED:sha256-fingerprint]` the moment it is
+  matched; the raw value never reaches terminal output, JSON, HTML,
+  annotations, summaries, or logs.
+- Static analysis has **false positives and false negatives**. Findings are
+  evidence for review, not verdicts.
+
+## Schema stability
+
+The JSON output is versioned and additive-first — see [SCHEMA.md](SCHEMA.md).
+Consumers must ignore unknown fields. The field names `autonomy_level`,
+`loss_scenarios`, `liveness_state`, `policy_lines`, and `exposure_class` are
+reserved for future versions. Treat `stoa-registry.json` as a CI artifact;
+committing it to the repository is not recommended.
+
+## Limitations
+
+- Regex and pattern-based; no AST or semantic analysis.
+- No runtime behavior: capability evidence does not prove a code path
+  executes, and call sites are not API call counts.
+- No cross-repository or organization-wide infrastructure visibility: a
+  control "not observed in this file" may exist elsewhere.
+- No definitive ownership inference — "last touched by" is commit history,
+  not ownership; CODEOWNERS support covers the common gitignore-style subset
+  of GitHub's pattern syntax (order-sensitive last-match-wins; bracket
+  character classes and per-file section syntax are not supported).
+- Python, JavaScript, and TypeScript only.
+- Only the repository-root `.gitignore` and `.stoaignore` are consulted.
+
+## CI bypass considerations
+
+- The workflow installs a **pinned** Stoa release from PyPI rather than
+  executing scanner code from the pull request, so a PR cannot modify the
+  scanner to bypass enforcement.
+- Protect `.github/workflows/stoa.yml`, `stoa.toml`, and `.stoaignore` with
+  CODEOWNERS and branch protection — a PR that edits them can weaken the
+  gate, so those edits deserve review.
+- Inline suppressions (`# stoa: ignore[...]`) change what the gate sees;
+  review them like any other security-relevant change.
+
+## Development
+
+```bash
+python -m venv .venv && .venv/bin/pip install -e ".[dev]"
+.venv/bin/pytest
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

stoa_agent_risk-0.1.0/README.md

@@ -0,0 +1,202 @@
+# Stoa
+
+**A local-first AI agent inventory and risk scanner** that identifies agent
+candidates with supporting evidence, maps their capabilities and integrations,
+and prevents newly introduced high-confidence critical risks from entering
+the codebase.
+
+Stoa scans Python, JavaScript, and TypeScript repositories statically — no
+runtime hooks, no uploads, no accounts.
+
+## What Stoa does
+
+- **Discovers likely AI agents** (LangChain, LangGraph, CrewAI, AutoGen,
+  LlamaIndex, OpenAI Agents SDK, PydanticAI, Bedrock Agents, Semantic Kernel,
+  LiteLLM, and raw provider calls) using weighted evidence, and shows exactly
+  *why* each candidate was detected.
+- **Maps providers, frameworks, integrations, and capabilities** — e.g. an
+  agent candidate with payment access, database reads, and Slack messaging.
+- **Detects high-confidence risks**: hardcoded credentials, hardcoded
+  passwords, interpolated SQL, swallowed exceptions, insecure HTTP, missing
+  request timeouts, and control-review prompts.
+- **Produces local reports**: a manager-friendly self-contained HTML report
+  and a deterministic, versioned JSON registry.
+- **Gates only newly introduced critical findings by default** — existing
+  debt never blocks an unrelated pull request.
+
+Stoa reports *candidates* and *evidence*, not certainties. A "control not
+observed" prompt is a review nudge, not a proven vulnerability.
+
+## Quick start
+
+```bash
+pipx install stoa-agent-risk
+cd my-repository
+stoa scan .
+open stoa-report.html
+```
+
+`stoa scan .` writes `stoa-report.html` and `stoa-registry.json` and exits 0
+(report-only) unless a gate is configured. The JSON is designed to be read by
+coding assistants too:
+
+```bash
+stoa scan . --json stoa-registry.json
+```
+
+## GitHub Actions
+
+```bash
+stoa init github
+```
+
+This creates (without overwriting existing files — use `--force` to
+overwrite):
+
+- `.github/workflows/stoa.yml` — full-history checkout, pinned Stoa install,
+  full-repository scan, diff against the PR base branch, GitHub annotations,
+  a job summary, uploaded HTML/JSON artifacts, and a gate that fails **only**
+  when the PR introduces a new high-confidence critical finding.
+- `.stoaignore` — gitignore-style path exclusions.
+- `stoa.toml` — configuration with documented defaults.
+
+## CLI
+
+```bash
+stoa scan [PATH]
+  --html PATH               HTML report (default stoa-report.html)
+  --json PATH               JSON registry (default stoa-registry.json)
+  --base GIT_REF            enable diff-aware behavior (e.g. origin/main)
+  --strict                  fail on all unsuppressed high-confidence criticals
+  --fail-on {none,high,critical}
+  --fail-on-new {none,high,critical}   applies with --base
+  --github-annotations      emit ::error/::warning workflow commands
+  --summary-file PATH       write a GitHub job-summary Markdown file
+  --config PATH             explicit stoa.toml
+  --no-git                  skip git metadata
+  --include / --exclude     extra path patterns (repeatable)
+  --verbose / --quiet
+```
+
+Exit codes: `0` gate passed · `1` gate failed · `2` invalid arguments or
+configuration · `3` scanner execution error.
+
+Only high-confidence findings from gate-eligible rules (SEC001, SEC002) can
+fail a scan; SQL-interpolation, network, and review-prompt rules report but
+never gate, because static regex analysis cannot prove exploitability.
+
+## Suppression
+
+Inline, on the same or preceding line, always with explicit rule IDs:
+
+```python
+# stoa: ignore[SEC003] trusted identifier from internal enum
+query = f"SELECT * FROM {table_name}"
+```
+
+```javascript
+const endpoint = "http://staging.internal.corp"; // stoa: ignore[NET001]
+```
+
+File-wide:
+
+```python
+# stoa: ignore-file[CTRL001,CTRL002]
+```
+
+Suppressed findings are counted and shown in reports — never silently
+discarded. There is no blanket `ignore-all`.
+
+## Configuration
+
+`stoa.toml` in the repository root (all values shown are defaults):
+
+```toml
+fail_on = "none"          # gate on all findings at/above this severity
+fail_on_new = "critical"  # gate on newly introduced findings (with --base)
+max_file_bytes = 1000000
+follow_symlinks = false
+respect_gitignore = true
+
+ignore_paths = [          # merged with built-in defaults (node_modules, dist, …)
+  "tests/snapshots/**",
+]
+
+[severity]                # per-rule severity overrides
+NET001 = "info"
+
+[rules]                   # per-rule enable/disable
+CTRL003 = false
+```
+
+`.stoaignore` uses gitignore syntax for path exclusions. Tests and fixtures
+are *not* ignored by default — secret scanning is still useful there — but
+they are downweighted for agent detection and placeholder-secret heuristics
+apply.
+
+## Rules
+
+| Rule | Title | Default severity | Gates? |
+|---|---|---|---|
+| SEC001 | Possible hardcoded API credential | critical | yes (high confidence only) |
+| SEC002 | Possible hardcoded password | high (critical at high confidence) | yes (high confidence only) |
+| SEC003 | Interpolated SQL statement | high | no |
+| REL001 | Swallowed exception | medium | no |
+| NET001 | Insecure non-local HTTP endpoint | medium | no |
+| NET002 | Request timeout not observed | medium | no |
+| CTRL001–003 | Auth / validation / rate-limit control not observed | info | never |
+
+## Security model
+
+- **Local-first.** No source code is uploaded anywhere; Stoa makes no network
+  calls and collects no telemetry.
+- **Secrets are redacted before serialization.** A detected credential is
+  replaced with `prefix…[REDACTED:sha256-fingerprint]` the moment it is
+  matched; the raw value never reaches terminal output, JSON, HTML,
+  annotations, summaries, or logs.
+- Static analysis has **false positives and false negatives**. Findings are
+  evidence for review, not verdicts.
+
+## Schema stability
+
+The JSON output is versioned and additive-first — see [SCHEMA.md](SCHEMA.md).
+Consumers must ignore unknown fields. The field names `autonomy_level`,
+`loss_scenarios`, `liveness_state`, `policy_lines`, and `exposure_class` are
+reserved for future versions. Treat `stoa-registry.json` as a CI artifact;
+committing it to the repository is not recommended.
+
+## Limitations
+
+- Regex and pattern-based; no AST or semantic analysis.
+- No runtime behavior: capability evidence does not prove a code path
+  executes, and call sites are not API call counts.
+- No cross-repository or organization-wide infrastructure visibility: a
+  control "not observed in this file" may exist elsewhere.
+- No definitive ownership inference — "last touched by" is commit history,
+  not ownership; CODEOWNERS support covers the common gitignore-style subset
+  of GitHub's pattern syntax (order-sensitive last-match-wins; bracket
+  character classes and per-file section syntax are not supported).
+- Python, JavaScript, and TypeScript only.
+- Only the repository-root `.gitignore` and `.stoaignore` are consulted.
+
+## CI bypass considerations
+
+- The workflow installs a **pinned** Stoa release from PyPI rather than
+  executing scanner code from the pull request, so a PR cannot modify the
+  scanner to bypass enforcement.
+- Protect `.github/workflows/stoa.yml`, `stoa.toml`, and `.stoaignore` with
+  CODEOWNERS and branch protection — a PR that edits them can weaken the
+  gate, so those edits deserve review.
+- Inline suppressions (`# stoa: ignore[...]`) change what the gate sees;
+  review them like any other security-relevant change.
+
+## Development
+
+```bash
+python -m venv .venv && .venv/bin/pip install -e ".[dev]"
+.venv/bin/pytest
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

stoa_agent_risk-0.1.0/pyproject.toml

@@ -0,0 +1,50 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "stoa-agent-risk"
+version = "0.1.0"
+description = "Local-first AI agent inventory and risk scanner: finds agent candidates with evidence, maps capabilities and integrations, and gates newly introduced high-confidence critical risks."
+readme = "README.md"
+license = { file = "LICENSE" }
+requires-python = ">=3.10"
+authors = [{ name = "Ved Upadhyay", email = "iamved05@gmail.com" }]
+keywords = ["ai-agents", "security", "static-analysis", "llm", "sast"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Security",
+    "Topic :: Software Development :: Quality Assurance",
+]
+dependencies = [
+    "pathspec>=0.11",
+    "tomli>=2.0; python_version < '3.11'",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=7.4"]
+
+[project.scripts]
+stoa = "stoa.cli:main"
+
+[project.urls]
+Homepage = "https://stoa-features.vercel.app"
+Repository = "https://github.com/iamved/stoa-agent-risk"
+Issues = "https://github.com/iamved/stoa-agent-risk/issues"
+Documentation = "https://github.com/iamved/stoa-agent-risk#readme"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+stoa = ["templates/*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

stoa_agent_risk-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

stoa_agent_risk-0.1.0/src/stoa/__init__.py

@@ -0,0 +1,5 @@
+"""Stoa: local-first AI agent inventory and risk scanner."""
+
+__version__ = "0.1.0"
+
+SCHEMA_VERSION = "1.0"