agentveil-posture 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- agentveil_posture-0.1.0/LICENSE +21 -0
- agentveil_posture-0.1.0/PKG-INFO +293 -0
- agentveil_posture-0.1.0/README.md +264 -0
- agentveil_posture-0.1.0/pyproject.toml +47 -0
- agentveil_posture-0.1.0/setup.cfg +4 -0
- agentveil_posture-0.1.0/src/agentveil_posture/__init__.py +6 -0
- agentveil_posture-0.1.0/src/agentveil_posture/cli.py +98 -0
- agentveil_posture-0.1.0/src/agentveil_posture/report.py +210 -0
- agentveil_posture-0.1.0/src/agentveil_posture/rules/__init__.py +21 -0
- agentveil_posture-0.1.0/src/agentveil_posture/rules/identity.py +51 -0
- agentveil_posture-0.1.0/src/agentveil_posture/rules/manifest.py +166 -0
- agentveil_posture-0.1.0/src/agentveil_posture/rules/parsing.py +72 -0
- agentveil_posture-0.1.0/src/agentveil_posture/rules/workflow.py +182 -0
- agentveil_posture-0.1.0/src/agentveil_posture/scanner.py +61 -0
- agentveil_posture-0.1.0/src/agentveil_posture.egg-info/PKG-INFO +293 -0
- agentveil_posture-0.1.0/src/agentveil_posture.egg-info/SOURCES.txt +26 -0
- agentveil_posture-0.1.0/src/agentveil_posture.egg-info/dependency_links.txt +1 -0
- agentveil_posture-0.1.0/src/agentveil_posture.egg-info/entry_points.txt +2 -0
- agentveil_posture-0.1.0/src/agentveil_posture.egg-info/requires.txt +4 -0
- agentveil_posture-0.1.0/src/agentveil_posture.egg-info/top_level.txt +1 -0
- agentveil_posture-0.1.0/tests/test_action_manifest.py +29 -0
- agentveil_posture-0.1.0/tests/test_cli.py +232 -0
- agentveil_posture-0.1.0/tests/test_fixtures.py +32 -0
- agentveil_posture-0.1.0/tests/test_hard_constraints.py +60 -0
- agentveil_posture-0.1.0/tests/test_identity_private_key_rule.py +117 -0
- agentveil_posture-0.1.0/tests/test_manifest_rules.py +264 -0
- agentveil_posture-0.1.0/tests/test_report_schema.py +163 -0
- agentveil_posture-0.1.0/tests/test_workflow_rules.py +442 -0
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 AgentVeil Protocol contributors
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,293 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: agentveil-posture
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Pre-deployment posture checks for risky AI agent capabilities.
|
|
5
|
+
Author: AgentVeil Protocol contributors
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Project-URL: Homepage, https://agentveil.dev
|
|
8
|
+
Project-URL: Repository, https://github.com/agentveil-protocol/agentveil-posture
|
|
9
|
+
Project-URL: Issues, https://github.com/agentveil-protocol/agentveil-posture/issues
|
|
10
|
+
Project-URL: Documentation, https://github.com/agentveil-protocol/agentveil-posture#readme
|
|
11
|
+
Keywords: security,agent,mcp,posture,github-actions,ai-agents
|
|
12
|
+
Classifier: Development Status :: 3 - Alpha
|
|
13
|
+
Classifier: Environment :: Console
|
|
14
|
+
Classifier: Intended Audience :: Developers
|
|
15
|
+
Classifier: Programming Language :: Python :: 3
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
21
|
+
Classifier: Topic :: Security
|
|
22
|
+
Requires-Python: >=3.10
|
|
23
|
+
Description-Content-Type: text/markdown
|
|
24
|
+
License-File: LICENSE
|
|
25
|
+
Requires-Dist: PyYAML<7,>=6.0.1
|
|
26
|
+
Provides-Extra: test
|
|
27
|
+
Requires-Dist: pytest>=8; extra == "test"
|
|
28
|
+
Dynamic: license-file
|
|
29
|
+
|
|
30
|
+
# AgentVeil Posture
|
|
31
|
+
|
|
32
|
+
<p align="center">
|
|
33
|
+
<img src="docs/agentveil-posture-logo.png" alt="AgentVeil Posture logo" width="180">
|
|
34
|
+
</p>
|
|
35
|
+
|
|
36
|
+
[](LICENSE)
|
|
37
|
+
[](https://pypi.org/project/agentveil-posture/)
|
|
38
|
+
[](https://github.com/agentveil-protocol/agentveil-posture/actions/workflows/posture-self-test.yml)
|
|
39
|
+
[](https://www.python.org/downloads/)
|
|
40
|
+
[](https://github.com/agentveil-protocol/agentveil-posture/stargazers)
|
|
41
|
+
[](#use-as-a-github-action)
|
|
42
|
+
[](#hard-constraints)
|
|
43
|
+
|
|
44
|
+
**Pre-deployment posture check for AI agents. Find risky capabilities before they become production incidents.**
|
|
45
|
+
|
|
46
|
+
`agentveil-posture` is a pre-deployment, static, local-only scanner that flags
|
|
47
|
+
risky AI-agent and GitHub-workflow posture issues. No telemetry, no network
|
|
48
|
+
calls, no project code execution. v0.1 ships five high-severity GitHub-focused
|
|
49
|
+
rules.
|
|
50
|
+
|
|
51
|
+
[Quick Start](#quick-start) |
|
|
52
|
+
[What a finding looks like](#what-a-finding-looks-like) |
|
|
53
|
+
[Detection scope](#detection-scope-v01) |
|
|
54
|
+
[GitHub Action](#use-as-a-github-action) |
|
|
55
|
+
[Why this exists](#why-this-exists)
|
|
56
|
+
|
|
57
|
+
---
|
|
58
|
+
|
|
59
|
+
## Quick Start
|
|
60
|
+
|
|
61
|
+
```bash
|
|
62
|
+
pip install agentveil-posture
|
|
63
|
+
agentveil posture scan --path . --output report.json
|
|
64
|
+
cat report.json
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
That is the whole flow. The scanner is read-only: it does not modify your
|
|
68
|
+
files, run your code, or send data over the network.
|
|
69
|
+
|
|
70
|
+
To fail CI when findings meet a threshold, add `--fail-on`:
|
|
71
|
+
|
|
72
|
+
```bash
|
|
73
|
+
agentveil posture scan --path . --output report.json --fail-on high
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
## What a Finding Looks Like
|
|
77
|
+
|
|
78
|
+
```json
|
|
79
|
+
{
|
|
80
|
+
"rule_id": "workflow.deploy_without_approval",
|
|
81
|
+
"severity": "high",
|
|
82
|
+
"file": ".github/workflows/deploy.yml",
|
|
83
|
+
"line": 12,
|
|
84
|
+
"message": "Deployment workflow appears to run without an approval gate.",
|
|
85
|
+
"remediation": "Add a protected GitHub environment or explicit manual approval before production deploy, release, or publish steps."
|
|
86
|
+
}
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
Every finding contains rule ID, severity, repository-relative file path, line
|
|
90
|
+
number when available, redacted message, and remediation pointer. Raw secrets,
|
|
91
|
+
command bodies, and key material never appear in the report.
|
|
92
|
+
|
|
93
|
+
## Detection Scope (v0.1)
|
|
94
|
+
|
|
95
|
+
All v0.1 rules are reported as `high` severity.
|
|
96
|
+
|
|
97
|
+
| Rule | What it flags |
|
|
98
|
+
|---|---|
|
|
99
|
+
| `bypass.direct_github_token` | Direct GitHub PAT/token references in workflows or agent manifests |
|
|
100
|
+
| `workflow.deploy_without_approval` | Deploy/release/publish steps without an approval gate |
|
|
101
|
+
| `workflow.pull_request_target_secrets_risk` | `pull_request_target` workflows that combine privileged context with checkout, run, or secrets |
|
|
102
|
+
| `tool.shell_without_approval` | Agent tool manifests that enable shell execution without an approval flag |
|
|
103
|
+
| `identity.private_key_unencrypted` | Unencrypted PEM private key files committed to the repo |
|
|
104
|
+
|
|
105
|
+
## Install
|
|
106
|
+
|
|
107
|
+
<details>
|
|
108
|
+
<summary><b>From PyPI (recommended)</b></summary>
|
|
109
|
+
|
|
110
|
+
```bash
|
|
111
|
+
pip install agentveil-posture
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
</details>
|
|
115
|
+
|
|
116
|
+
<details>
|
|
117
|
+
<summary><b>From GitHub release</b></summary>
|
|
118
|
+
|
|
119
|
+
```bash
|
|
120
|
+
pip install git+https://github.com/agentveil-protocol/agentveil-posture@v0.1.0
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
</details>
|
|
124
|
+
|
|
125
|
+
<details>
|
|
126
|
+
<summary><b>From source (development)</b></summary>
|
|
127
|
+
|
|
128
|
+
```bash
|
|
129
|
+
git clone https://github.com/agentveil-protocol/agentveil-posture
|
|
130
|
+
cd agentveil-posture
|
|
131
|
+
pip install -e .
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
</details>
|
|
135
|
+
|
|
136
|
+
## Use as a GitHub Action
|
|
137
|
+
|
|
138
|
+
Use the action from the same repository:
|
|
139
|
+
|
|
140
|
+
```yaml
|
|
141
|
+
- uses: agentveil-protocol/agentveil-posture@v0.1.0
|
|
142
|
+
with:
|
|
143
|
+
path: "."
|
|
144
|
+
output: agentveil-posture-report.json
|
|
145
|
+
fail-on: high
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
The action requires Python 3.10 or newer on the runner. It writes the report
|
|
149
|
+
path to the `report` output and does not upload data to AgentVeil. Omit
|
|
150
|
+
`fail-on` to keep review-only behavior.
|
|
151
|
+
|
|
152
|
+
For GitHub Code Scanning, write SARIF and upload it with CodeQL:
|
|
153
|
+
|
|
154
|
+
```yaml
|
|
155
|
+
- uses: agentveil-protocol/agentveil-posture@v0.1.0
|
|
156
|
+
with:
|
|
157
|
+
path: "."
|
|
158
|
+
output: agentveil-posture.sarif
|
|
159
|
+
format: sarif
|
|
160
|
+
|
|
161
|
+
- uses: github/codeql-action/upload-sarif@v3
|
|
162
|
+
with:
|
|
163
|
+
sarif_file: agentveil-posture.sarif
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
## Pre-commit Hook
|
|
167
|
+
|
|
168
|
+
Run AgentVeil Posture as a [pre-commit](https://pre-commit.com) hook to catch
|
|
169
|
+
posture issues before they reach the remote.
|
|
170
|
+
|
|
171
|
+
Add to your `.pre-commit-config.yaml`:
|
|
172
|
+
|
|
173
|
+
```yaml
|
|
174
|
+
repos:
|
|
175
|
+
- repo: https://github.com/agentveil-protocol/agentveil-posture
|
|
176
|
+
rev: v0.1.0
|
|
177
|
+
hooks:
|
|
178
|
+
- id: agentveil-posture
|
|
179
|
+
args: ["--fail-on", "high"]
|
|
180
|
+
```
|
|
181
|
+
|
|
182
|
+
Then install:
|
|
183
|
+
|
|
184
|
+
```bash
|
|
185
|
+
pre-commit install
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
The hook generates `agentveil-posture-report.json` on every commit. Omit
|
|
189
|
+
`args` for review-only behavior, or use `--fail-on` to block commits when
|
|
190
|
+
findings meet the selected threshold.
|
|
191
|
+
|
|
192
|
+
## Triaging Findings
|
|
193
|
+
|
|
194
|
+
`agentveil-posture` flags **posture surfaces**: places where an AI agent or
|
|
195
|
+
workflow has direct capability to do something risky. Most findings are
|
|
196
|
+
**review items**, not incidents:
|
|
197
|
+
|
|
198
|
+
- **`bypass.direct_github_token`** commonly appears on stale-bots,
|
|
199
|
+
release-bots, CI publish steps, and label-management workflows that
|
|
200
|
+
legitimately use the auto-injected `secrets.GITHUB_TOKEN`. The rule fires
|
|
201
|
+
by design: the workflow holds direct GitHub write capability and that is a
|
|
202
|
+
posture surface worth surfacing, even when expected.
|
|
203
|
+
- **`workflow.deploy_without_approval`** may flag deploy paths that have
|
|
204
|
+
approval mechanisms the static scanner cannot see, such as manual job
|
|
205
|
+
dispatch, branch protection, or external reviewer chains. Verify against
|
|
206
|
+
your actual approval flow before treating as incident.
|
|
207
|
+
- **`workflow.pull_request_target_secrets_risk`** flags risky combinations,
|
|
208
|
+
but some `pull_request_target` workflows are correctly scoped to label-only
|
|
209
|
+
or metadata-only operations. Re-check the actual job content.
|
|
210
|
+
- **`tool.shell_without_approval`** flags inline shell capability
|
|
211
|
+
declarations. Tools referenced by name, such as `search_tool` in CrewAI,
|
|
212
|
+
are not detected; only literal `shell:` or `bash:` keys are.
|
|
213
|
+
- **`identity.private_key_unencrypted`** is the most reliably actionable
|
|
214
|
+
finding: committed unencrypted private keys are usually real issues.
|
|
215
|
+
|
|
216
|
+
Use posture-check to surface review items for human triage, not to auto-block
|
|
217
|
+
CI or replace SAST/secret-scanning tools.
|
|
218
|
+
|
|
219
|
+
## Why This Exists
|
|
220
|
+
|
|
221
|
+
AI agents increasingly touch production credentials, deploy workflows, and
|
|
222
|
+
developer infrastructure. AgentVeil Posture is the first step: find risky
|
|
223
|
+
capabilities before deployment and before they become incidents.
|
|
224
|
+
|
|
225
|
+
```text
|
|
226
|
+
+----------+ +----------+ +----------+
|
|
227
|
+
| FIND | | DECIDE | | PROVE |
|
|
228
|
+
| risky | ---> | what is | ---> | what |
|
|
229
|
+
| caps | | allowed | | happened |
|
|
230
|
+
+----------+ +----------+ +----------+
|
|
231
|
+
you are here roadmap roadmap
|
|
232
|
+
v0.1 Posture
|
|
233
|
+
```
|
|
234
|
+
|
|
235
|
+
| | Posture does | Posture does not |
|
|
236
|
+
|---|---|---|
|
|
237
|
+
| Scope | Static analysis and posture risk patterns | Approval, blocking, or execution of agent actions |
|
|
238
|
+
| Effects | Read-only file inspection | Code execution, network calls, or file mutation |
|
|
239
|
+
| Output | Redacted JSON findings | Secret values, command bodies, or key bytes |
|
|
240
|
+
|
|
241
|
+
For the broader AgentVeil project, see [agentveil.dev](https://agentveil.dev).
|
|
242
|
+
|
|
243
|
+
## Hard Constraints
|
|
244
|
+
|
|
245
|
+
The scanner is designed to be:
|
|
246
|
+
|
|
247
|
+
- **offline**: no network calls
|
|
248
|
+
- **telemetry-free**: no usage data collected
|
|
249
|
+
- **read-only**: does not modify scanned files
|
|
250
|
+
- **static-only**: does not execute scanned project code
|
|
251
|
+
- **secret-safe**: reports only redacted findings
|
|
252
|
+
|
|
253
|
+
Private-key checks use file metadata and bounded header sniffing only.
|
|
254
|
+
|
|
255
|
+
## Dependency Policy
|
|
256
|
+
|
|
257
|
+
Runtime dependencies are intentionally minimal:
|
|
258
|
+
|
|
259
|
+
- Python `>=3.10`
|
|
260
|
+
- `PyYAML>=6.0.1,<7`
|
|
261
|
+
|
|
262
|
+
Additional runtime dependencies require explicit justification in
|
|
263
|
+
[PLAN.md](PLAN.md).
|
|
264
|
+
|
|
265
|
+
## Known Limitations
|
|
266
|
+
|
|
267
|
+
`agentveil-posture` v0.1 is a best-effort heuristic scanner, not an exhaustive
|
|
268
|
+
security audit.
|
|
269
|
+
|
|
270
|
+
- Some rules may produce false positives or false negatives.
|
|
271
|
+
- Oversized, unreadable, or malformed inputs may be skipped without per-file
|
|
272
|
+
skip reasons.
|
|
273
|
+
- YAML parsing is bounded, but carefully crafted YAML within the v0.1 alias
|
|
274
|
+
limit can still consume parser memory.
|
|
275
|
+
- The repository includes an intentional synthetic PEM-shaped fixture for
|
|
276
|
+
scanner tests. It is not a real private key.
|
|
277
|
+
|
|
278
|
+
## Community
|
|
279
|
+
|
|
280
|
+
- [Star this repo](https://github.com/agentveil-protocol/agentveil-posture/stargazers)
|
|
281
|
+
if Posture helps your team.
|
|
282
|
+
- [Open an issue](https://github.com/agentveil-protocol/agentveil-posture/issues)
|
|
283
|
+
for bugs, false positives, or rule suggestions.
|
|
284
|
+
- See [PLAN.md](PLAN.md) for the v0.1 spec, schema details, and v0.2 backlog.
|
|
285
|
+
|
|
286
|
+
## License
|
|
287
|
+
|
|
288
|
+
MIT. See [LICENSE](LICENSE).
|
|
289
|
+
|
|
290
|
+
---
|
|
291
|
+
|
|
292
|
+
Part of the [AgentVeil project](https://agentveil.dev): action control for
|
|
293
|
+
autonomous agents.
|
|
@@ -0,0 +1,264 @@
|
|
|
1
|
+
# AgentVeil Posture
|
|
2
|
+
|
|
3
|
+
<p align="center">
|
|
4
|
+
<img src="docs/agentveil-posture-logo.png" alt="AgentVeil Posture logo" width="180">
|
|
5
|
+
</p>
|
|
6
|
+
|
|
7
|
+
[](LICENSE)
|
|
8
|
+
[](https://pypi.org/project/agentveil-posture/)
|
|
9
|
+
[](https://github.com/agentveil-protocol/agentveil-posture/actions/workflows/posture-self-test.yml)
|
|
10
|
+
[](https://www.python.org/downloads/)
|
|
11
|
+
[](https://github.com/agentveil-protocol/agentveil-posture/stargazers)
|
|
12
|
+
[](#use-as-a-github-action)
|
|
13
|
+
[](#hard-constraints)
|
|
14
|
+
|
|
15
|
+
**Pre-deployment posture check for AI agents. Find risky capabilities before they become production incidents.**
|
|
16
|
+
|
|
17
|
+
`agentveil-posture` is a pre-deployment, static, local-only scanner that flags
|
|
18
|
+
risky AI-agent and GitHub-workflow posture issues. No telemetry, no network
|
|
19
|
+
calls, no project code execution. v0.1 ships five high-severity GitHub-focused
|
|
20
|
+
rules.
|
|
21
|
+
|
|
22
|
+
[Quick Start](#quick-start) |
|
|
23
|
+
[What a finding looks like](#what-a-finding-looks-like) |
|
|
24
|
+
[Detection scope](#detection-scope-v01) |
|
|
25
|
+
[GitHub Action](#use-as-a-github-action) |
|
|
26
|
+
[Why this exists](#why-this-exists)
|
|
27
|
+
|
|
28
|
+
---
|
|
29
|
+
|
|
30
|
+
## Quick Start
|
|
31
|
+
|
|
32
|
+
```bash
|
|
33
|
+
pip install agentveil-posture
|
|
34
|
+
agentveil posture scan --path . --output report.json
|
|
35
|
+
cat report.json
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
That is the whole flow. The scanner is read-only: it does not modify your
|
|
39
|
+
files, run your code, or send data over the network.
|
|
40
|
+
|
|
41
|
+
To fail CI when findings meet a threshold, add `--fail-on`:
|
|
42
|
+
|
|
43
|
+
```bash
|
|
44
|
+
agentveil posture scan --path . --output report.json --fail-on high
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
## What a Finding Looks Like
|
|
48
|
+
|
|
49
|
+
```json
|
|
50
|
+
{
|
|
51
|
+
"rule_id": "workflow.deploy_without_approval",
|
|
52
|
+
"severity": "high",
|
|
53
|
+
"file": ".github/workflows/deploy.yml",
|
|
54
|
+
"line": 12,
|
|
55
|
+
"message": "Deployment workflow appears to run without an approval gate.",
|
|
56
|
+
"remediation": "Add a protected GitHub environment or explicit manual approval before production deploy, release, or publish steps."
|
|
57
|
+
}
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
Every finding contains rule ID, severity, repository-relative file path, line
|
|
61
|
+
number when available, redacted message, and remediation pointer. Raw secrets,
|
|
62
|
+
command bodies, and key material never appear in the report.
|
|
63
|
+
|
|
64
|
+
## Detection Scope (v0.1)
|
|
65
|
+
|
|
66
|
+
All v0.1 rules are reported as `high` severity.
|
|
67
|
+
|
|
68
|
+
| Rule | What it flags |
|
|
69
|
+
|---|---|
|
|
70
|
+
| `bypass.direct_github_token` | Direct GitHub PAT/token references in workflows or agent manifests |
|
|
71
|
+
| `workflow.deploy_without_approval` | Deploy/release/publish steps without an approval gate |
|
|
72
|
+
| `workflow.pull_request_target_secrets_risk` | `pull_request_target` workflows that combine privileged context with checkout, run, or secrets |
|
|
73
|
+
| `tool.shell_without_approval` | Agent tool manifests that enable shell execution without an approval flag |
|
|
74
|
+
| `identity.private_key_unencrypted` | Unencrypted PEM private key files committed to the repo |
|
|
75
|
+
|
|
76
|
+
## Install
|
|
77
|
+
|
|
78
|
+
<details>
|
|
79
|
+
<summary><b>From PyPI (recommended)</b></summary>
|
|
80
|
+
|
|
81
|
+
```bash
|
|
82
|
+
pip install agentveil-posture
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
</details>
|
|
86
|
+
|
|
87
|
+
<details>
|
|
88
|
+
<summary><b>From GitHub release</b></summary>
|
|
89
|
+
|
|
90
|
+
```bash
|
|
91
|
+
pip install git+https://github.com/agentveil-protocol/agentveil-posture@v0.1.0
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
</details>
|
|
95
|
+
|
|
96
|
+
<details>
|
|
97
|
+
<summary><b>From source (development)</b></summary>
|
|
98
|
+
|
|
99
|
+
```bash
|
|
100
|
+
git clone https://github.com/agentveil-protocol/agentveil-posture
|
|
101
|
+
cd agentveil-posture
|
|
102
|
+
pip install -e .
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
</details>
|
|
106
|
+
|
|
107
|
+
## Use as a GitHub Action
|
|
108
|
+
|
|
109
|
+
Use the action from the same repository:
|
|
110
|
+
|
|
111
|
+
```yaml
|
|
112
|
+
- uses: agentveil-protocol/agentveil-posture@v0.1.0
|
|
113
|
+
with:
|
|
114
|
+
path: "."
|
|
115
|
+
output: agentveil-posture-report.json
|
|
116
|
+
fail-on: high
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
The action requires Python 3.10 or newer on the runner. It writes the report
|
|
120
|
+
path to the `report` output and does not upload data to AgentVeil. Omit
|
|
121
|
+
`fail-on` to keep review-only behavior.
|
|
122
|
+
|
|
123
|
+
For GitHub Code Scanning, write SARIF and upload it with CodeQL:
|
|
124
|
+
|
|
125
|
+
```yaml
|
|
126
|
+
- uses: agentveil-protocol/agentveil-posture@v0.1.0
|
|
127
|
+
with:
|
|
128
|
+
path: "."
|
|
129
|
+
output: agentveil-posture.sarif
|
|
130
|
+
format: sarif
|
|
131
|
+
|
|
132
|
+
- uses: github/codeql-action/upload-sarif@v3
|
|
133
|
+
with:
|
|
134
|
+
sarif_file: agentveil-posture.sarif
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
## Pre-commit Hook
|
|
138
|
+
|
|
139
|
+
Run AgentVeil Posture as a [pre-commit](https://pre-commit.com) hook to catch
|
|
140
|
+
posture issues before they reach the remote.
|
|
141
|
+
|
|
142
|
+
Add to your `.pre-commit-config.yaml`:
|
|
143
|
+
|
|
144
|
+
```yaml
|
|
145
|
+
repos:
|
|
146
|
+
- repo: https://github.com/agentveil-protocol/agentveil-posture
|
|
147
|
+
rev: v0.1.0
|
|
148
|
+
hooks:
|
|
149
|
+
- id: agentveil-posture
|
|
150
|
+
args: ["--fail-on", "high"]
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
Then install:
|
|
154
|
+
|
|
155
|
+
```bash
|
|
156
|
+
pre-commit install
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
The hook generates `agentveil-posture-report.json` on every commit. Omit
|
|
160
|
+
`args` for review-only behavior, or use `--fail-on` to block commits when
|
|
161
|
+
findings meet the selected threshold.
|
|
162
|
+
|
|
163
|
+
## Triaging Findings
|
|
164
|
+
|
|
165
|
+
`agentveil-posture` flags **posture surfaces**: places where an AI agent or
|
|
166
|
+
workflow has direct capability to do something risky. Most findings are
|
|
167
|
+
**review items**, not incidents:
|
|
168
|
+
|
|
169
|
+
- **`bypass.direct_github_token`** commonly appears on stale-bots,
|
|
170
|
+
release-bots, CI publish steps, and label-management workflows that
|
|
171
|
+
legitimately use the auto-injected `secrets.GITHUB_TOKEN`. The rule fires
|
|
172
|
+
by design: the workflow holds direct GitHub write capability and that is a
|
|
173
|
+
posture surface worth surfacing, even when expected.
|
|
174
|
+
- **`workflow.deploy_without_approval`** may flag deploy paths that have
|
|
175
|
+
approval mechanisms the static scanner cannot see, such as manual job
|
|
176
|
+
dispatch, branch protection, or external reviewer chains. Verify against
|
|
177
|
+
your actual approval flow before treating as incident.
|
|
178
|
+
- **`workflow.pull_request_target_secrets_risk`** flags risky combinations,
|
|
179
|
+
but some `pull_request_target` workflows are correctly scoped to label-only
|
|
180
|
+
or metadata-only operations. Re-check the actual job content.
|
|
181
|
+
- **`tool.shell_without_approval`** flags inline shell capability
|
|
182
|
+
declarations. Tools referenced by name, such as `search_tool` in CrewAI,
|
|
183
|
+
are not detected; only literal `shell:` or `bash:` keys are.
|
|
184
|
+
- **`identity.private_key_unencrypted`** is the most reliably actionable
|
|
185
|
+
finding: committed unencrypted private keys are usually real issues.
|
|
186
|
+
|
|
187
|
+
Use posture-check to surface review items for human triage, not to auto-block
|
|
188
|
+
CI or replace SAST/secret-scanning tools.
|
|
189
|
+
|
|
190
|
+
## Why This Exists
|
|
191
|
+
|
|
192
|
+
AI agents increasingly touch production credentials, deploy workflows, and
|
|
193
|
+
developer infrastructure. AgentVeil Posture is the first step: find risky
|
|
194
|
+
capabilities before deployment and before they become incidents.
|
|
195
|
+
|
|
196
|
+
```text
|
|
197
|
+
+----------+ +----------+ +----------+
|
|
198
|
+
| FIND | | DECIDE | | PROVE |
|
|
199
|
+
| risky | ---> | what is | ---> | what |
|
|
200
|
+
| caps | | allowed | | happened |
|
|
201
|
+
+----------+ +----------+ +----------+
|
|
202
|
+
you are here roadmap roadmap
|
|
203
|
+
v0.1 Posture
|
|
204
|
+
```
|
|
205
|
+
|
|
206
|
+
| | Posture does | Posture does not |
|
|
207
|
+
|---|---|---|
|
|
208
|
+
| Scope | Static analysis and posture risk patterns | Approval, blocking, or execution of agent actions |
|
|
209
|
+
| Effects | Read-only file inspection | Code execution, network calls, or file mutation |
|
|
210
|
+
| Output | Redacted JSON findings | Secret values, command bodies, or key bytes |
|
|
211
|
+
|
|
212
|
+
For the broader AgentVeil project, see [agentveil.dev](https://agentveil.dev).
|
|
213
|
+
|
|
214
|
+
## Hard Constraints
|
|
215
|
+
|
|
216
|
+
The scanner is designed to be:
|
|
217
|
+
|
|
218
|
+
- **offline**: no network calls
|
|
219
|
+
- **telemetry-free**: no usage data collected
|
|
220
|
+
- **read-only**: does not modify scanned files
|
|
221
|
+
- **static-only**: does not execute scanned project code
|
|
222
|
+
- **secret-safe**: reports only redacted findings
|
|
223
|
+
|
|
224
|
+
Private-key checks use file metadata and bounded header sniffing only.
|
|
225
|
+
|
|
226
|
+
## Dependency Policy
|
|
227
|
+
|
|
228
|
+
Runtime dependencies are intentionally minimal:
|
|
229
|
+
|
|
230
|
+
- Python `>=3.10`
|
|
231
|
+
- `PyYAML>=6.0.1,<7`
|
|
232
|
+
|
|
233
|
+
Additional runtime dependencies require explicit justification in
|
|
234
|
+
[PLAN.md](PLAN.md).
|
|
235
|
+
|
|
236
|
+
## Known Limitations
|
|
237
|
+
|
|
238
|
+
`agentveil-posture` v0.1 is a best-effort heuristic scanner, not an exhaustive
|
|
239
|
+
security audit.
|
|
240
|
+
|
|
241
|
+
- Some rules may produce false positives or false negatives.
|
|
242
|
+
- Oversized, unreadable, or malformed inputs may be skipped without per-file
|
|
243
|
+
skip reasons.
|
|
244
|
+
- YAML parsing is bounded, but carefully crafted YAML within the v0.1 alias
|
|
245
|
+
limit can still consume parser memory.
|
|
246
|
+
- The repository includes an intentional synthetic PEM-shaped fixture for
|
|
247
|
+
scanner tests. It is not a real private key.
|
|
248
|
+
|
|
249
|
+
## Community
|
|
250
|
+
|
|
251
|
+
- [Star this repo](https://github.com/agentveil-protocol/agentveil-posture/stargazers)
|
|
252
|
+
if Posture helps your team.
|
|
253
|
+
- [Open an issue](https://github.com/agentveil-protocol/agentveil-posture/issues)
|
|
254
|
+
for bugs, false positives, or rule suggestions.
|
|
255
|
+
- See [PLAN.md](PLAN.md) for the v0.1 spec, schema details, and v0.2 backlog.
|
|
256
|
+
|
|
257
|
+
## License
|
|
258
|
+
|
|
259
|
+
MIT. See [LICENSE](LICENSE).
|
|
260
|
+
|
|
261
|
+
---
|
|
262
|
+
|
|
263
|
+
Part of the [AgentVeil project](https://agentveil.dev): action control for
|
|
264
|
+
autonomous agents.
|
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["setuptools>=68"]
|
|
3
|
+
build-backend = "setuptools.build_meta"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "agentveil-posture"
|
|
7
|
+
version = "0.1.0"
|
|
8
|
+
description = "Pre-deployment posture checks for risky AI agent capabilities."
|
|
9
|
+
keywords = ["security", "agent", "mcp", "posture", "github-actions", "ai-agents"]
|
|
10
|
+
readme = "README.md"
|
|
11
|
+
requires-python = ">=3.10"
|
|
12
|
+
license = "MIT"
|
|
13
|
+
authors = [
|
|
14
|
+
{ name = "AgentVeil Protocol contributors" }
|
|
15
|
+
]
|
|
16
|
+
dependencies = [
|
|
17
|
+
"PyYAML>=6.0.1,<7"
|
|
18
|
+
]
|
|
19
|
+
classifiers = [
|
|
20
|
+
"Development Status :: 3 - Alpha",
|
|
21
|
+
"Environment :: Console",
|
|
22
|
+
"Intended Audience :: Developers",
|
|
23
|
+
"Programming Language :: Python :: 3",
|
|
24
|
+
"Programming Language :: Python :: 3.10",
|
|
25
|
+
"Programming Language :: Python :: 3.11",
|
|
26
|
+
"Programming Language :: Python :: 3.12",
|
|
27
|
+
"Programming Language :: Python :: 3.13",
|
|
28
|
+
"Programming Language :: Python :: 3.14",
|
|
29
|
+
"Topic :: Security"
|
|
30
|
+
]
|
|
31
|
+
|
|
32
|
+
[project.scripts]
|
|
33
|
+
agentveil = "agentveil_posture.cli:main"
|
|
34
|
+
|
|
35
|
+
[project.optional-dependencies]
|
|
36
|
+
test = [
|
|
37
|
+
"pytest>=8"
|
|
38
|
+
]
|
|
39
|
+
|
|
40
|
+
[project.urls]
|
|
41
|
+
Homepage = "https://agentveil.dev"
|
|
42
|
+
Repository = "https://github.com/agentveil-protocol/agentveil-posture"
|
|
43
|
+
Issues = "https://github.com/agentveil-protocol/agentveil-posture/issues"
|
|
44
|
+
Documentation = "https://github.com/agentveil-protocol/agentveil-posture#readme"
|
|
45
|
+
|
|
46
|
+
[tool.setuptools.packages.find]
|
|
47
|
+
where = ["src"]
|