agent-access-review 0.2.1__py3-none-any.whl
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.
- agent_access_review/__init__.py +4 -0
- agent_access_review/__main__.py +81 -0
- agent_access_review/catalog.yaml +102 -0
- agent_access_review/checks.py +197 -0
- agent_access_review/controls.yaml +91 -0
- agent_access_review/examples/agents.yaml +94 -0
- agent_access_review/examples/claude_desktop_config.json +29 -0
- agent_access_review/examples/vscode-mcp.json +14 -0
- agent_access_review/model.py +66 -0
- agent_access_review/parsers.py +320 -0
- agent_access_review/report.py +257 -0
- agent_access_review-0.2.1.dist-info/METADATA +346 -0
- agent_access_review-0.2.1.dist-info/RECORD +17 -0
- agent_access_review-0.2.1.dist-info/WHEEL +5 -0
- agent_access_review-0.2.1.dist-info/entry_points.txt +2 -0
- agent_access_review-0.2.1.dist-info/licenses/LICENSE +21 -0
- agent_access_review-0.2.1.dist-info/top_level.txt +1 -0
|
@@ -0,0 +1,81 @@
|
|
|
1
|
+
"""CLI.
|
|
2
|
+
|
|
3
|
+
agent-access-review demo review the bundled example agents
|
|
4
|
+
agent-access-review scan <paths> [--out review] [--as-of YYYY-MM-DD] [--fail-on high]
|
|
5
|
+
"""
|
|
6
|
+
from __future__ import annotations
|
|
7
|
+
|
|
8
|
+
import argparse
|
|
9
|
+
import sys
|
|
10
|
+
from datetime import date
|
|
11
|
+
from pathlib import Path
|
|
12
|
+
|
|
13
|
+
from .checks import run_all
|
|
14
|
+
from .model import SEVERITY_ORDER
|
|
15
|
+
from .parsers import discover
|
|
16
|
+
from .report import counts, write_all
|
|
17
|
+
|
|
18
|
+
EXAMPLES = Path(__file__).parent / 'examples'
|
|
19
|
+
EXAMPLES_AS_OF = date(2026, 10, 12) # the date the bundled examples were written for
|
|
20
|
+
|
|
21
|
+
EPILOG = """examples:
|
|
22
|
+
agent-access-review demo
|
|
23
|
+
agent-access-review scan ~/Library/Application\\ Support/Claude/claude_desktop_config.json
|
|
24
|
+
agent-access-review scan %APPDATA%\\Claude\\claude_desktop_config.json (Windows cmd)
|
|
25
|
+
agent-access-review scan ~/.cursor/mcp.json .vscode/mcp.json agents.yaml --fail-on high
|
|
26
|
+
"""
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
def main(argv: list[str] | None = None) -> int:
|
|
30
|
+
ap = argparse.ArgumentParser(prog='agent-access-review',
|
|
31
|
+
description='Access reviews for AI agents and MCP servers.',
|
|
32
|
+
epilog=EPILOG, formatter_class=argparse.RawDescriptionHelpFormatter)
|
|
33
|
+
sub = ap.add_subparsers(dest='cmd', required=True)
|
|
34
|
+
scan = sub.add_parser('scan', help='review agent configs and write the review packet')
|
|
35
|
+
scan.add_argument('paths', nargs='+', type=Path, help='MCP config files, agents.yaml manifests, or folders')
|
|
36
|
+
scan.add_argument('--out', type=Path, default=Path('review'), help='output folder (default: review)')
|
|
37
|
+
scan.add_argument('--as-of', type=date.fromisoformat, default=date.today(),
|
|
38
|
+
help='review date used for recertification, rotation and dormancy (default: today)')
|
|
39
|
+
scan.add_argument('--fail-on', choices=['high', 'medium', 'low', 'never'], default='never',
|
|
40
|
+
help='exit 1 if any finding is at or above this severity (for CI gates)')
|
|
41
|
+
demo = sub.add_parser('demo', help='review the bundled example agents (no setup needed)')
|
|
42
|
+
demo.add_argument('--out', type=Path, default=Path('review-demo'), help='output folder (default: review-demo)')
|
|
43
|
+
args = ap.parse_args(argv)
|
|
44
|
+
|
|
45
|
+
if args.cmd == 'demo':
|
|
46
|
+
print(f'Reviewing the bundled examples in {EXAMPLES} (as of {EXAMPLES_AS_OF}):\n')
|
|
47
|
+
return run([EXAMPLES], args.out, EXAMPLES_AS_OF, 'never', demo=True)
|
|
48
|
+
|
|
49
|
+
missing = [p for p in args.paths if not p.exists()]
|
|
50
|
+
if missing:
|
|
51
|
+
ap.error(f'not found: {", ".join(map(str, missing))}')
|
|
52
|
+
return run(args.paths, args.out, args.as_of, args.fail_on)
|
|
53
|
+
|
|
54
|
+
|
|
55
|
+
def run(paths: list[Path], out: Path, as_of: date, fail_on: str, demo: bool = False) -> int:
|
|
56
|
+
agents = discover(paths)
|
|
57
|
+
if not agents:
|
|
58
|
+
print('No MCP configs or agent manifests found.', file=sys.stderr)
|
|
59
|
+
return 2
|
|
60
|
+
|
|
61
|
+
results = [(a, run_all(a, as_of)) for a in agents]
|
|
62
|
+
written = write_all(results, out, as_of)
|
|
63
|
+
|
|
64
|
+
print(f'{"AGENT":<28} {"TOOLS":>5} {"HIGH":>5} {"MED":>5} {"LOW":>5}')
|
|
65
|
+
for agent, findings in results:
|
|
66
|
+
c = counts(findings)
|
|
67
|
+
print(f'{agent.id[:28]:<28} {len(agent.grants):>5} {c["high"]:>5} {c["medium"]:>5} {c["low"]:>5}')
|
|
68
|
+
print(f'\nReview packet: {written["report"]}\nDecision sheet: {written["sheet"]}\nOSCAL: {written["oscal"]}')
|
|
69
|
+
if demo:
|
|
70
|
+
print('\nOpen the review packet to see each agent\'s access, findings and recommended decisions.'
|
|
71
|
+
'\nNext: run `agent-access-review scan <your MCP config>` on your own setup.')
|
|
72
|
+
|
|
73
|
+
if fail_on != 'never':
|
|
74
|
+
floor = SEVERITY_ORDER[fail_on]
|
|
75
|
+
if any(SEVERITY_ORDER[f.severity] >= floor for _, fs in results for f in fs):
|
|
76
|
+
return 1
|
|
77
|
+
return 0
|
|
78
|
+
|
|
79
|
+
|
|
80
|
+
if __name__ == '__main__':
|
|
81
|
+
sys.exit(main())
|
|
@@ -0,0 +1,102 @@
|
|
|
1
|
+
# Capability profiles for well-known MCP servers. An MCP config only says *which*
|
|
2
|
+
# server runs, not what it can do, so this catalog is how a server name becomes an
|
|
3
|
+
# access grant. Anything not listed here is flagged as unclassified (AAR-12) rather
|
|
4
|
+
# than silently assumed safe. Add your organization's internal servers here.
|
|
5
|
+
#
|
|
6
|
+
# actions: read | write | delete | send | execute | admin
|
|
7
|
+
# data_classification: public | internal | confidential | restricted
|
|
8
|
+
# untrusted_input: the tool returns content an outsider can author (prompt-injection source)
|
|
9
|
+
# egress: the tool can move data outside the organization
|
|
10
|
+
# resource_from: how to name the resource: paths (filesystem args) | dsn (connection string)
|
|
11
|
+
# aliases: other names the same server runs under (official Docker image, uvx name)
|
|
12
|
+
|
|
13
|
+
servers:
|
|
14
|
+
"@modelcontextprotocol/server-filesystem":
|
|
15
|
+
tool: filesystem
|
|
16
|
+
aliases: [mcp/filesystem]
|
|
17
|
+
actions: [read, write, delete]
|
|
18
|
+
data_classification: confidential
|
|
19
|
+
resource_from: paths
|
|
20
|
+
|
|
21
|
+
"@modelcontextprotocol/server-github":
|
|
22
|
+
tool: github
|
|
23
|
+
actions: [read, write]
|
|
24
|
+
data_classification: confidential
|
|
25
|
+
untrusted_input: true
|
|
26
|
+
egress: true
|
|
27
|
+
|
|
28
|
+
"ghcr.io/github/github-mcp-server":
|
|
29
|
+
tool: github
|
|
30
|
+
actions: [read, write]
|
|
31
|
+
data_classification: confidential
|
|
32
|
+
untrusted_input: true
|
|
33
|
+
egress: true
|
|
34
|
+
|
|
35
|
+
"@modelcontextprotocol/server-postgres":
|
|
36
|
+
tool: postgres
|
|
37
|
+
aliases: [mcp/postgres]
|
|
38
|
+
actions: [read]
|
|
39
|
+
data_classification: restricted
|
|
40
|
+
resource_from: dsn
|
|
41
|
+
|
|
42
|
+
"@modelcontextprotocol/server-slack":
|
|
43
|
+
tool: slack
|
|
44
|
+
actions: [read, send]
|
|
45
|
+
data_classification: confidential
|
|
46
|
+
untrusted_input: true
|
|
47
|
+
egress: true
|
|
48
|
+
|
|
49
|
+
"mcp-server-fetch":
|
|
50
|
+
tool: fetch
|
|
51
|
+
aliases: [mcp/fetch]
|
|
52
|
+
actions: [read]
|
|
53
|
+
data_classification: public
|
|
54
|
+
untrusted_input: true
|
|
55
|
+
egress: true # a GET to an attacker URL can carry data in the query string
|
|
56
|
+
|
|
57
|
+
"@modelcontextprotocol/server-puppeteer":
|
|
58
|
+
tool: browser
|
|
59
|
+
aliases: [mcp/puppeteer]
|
|
60
|
+
actions: [read, send]
|
|
61
|
+
data_classification: public
|
|
62
|
+
untrusted_input: true
|
|
63
|
+
egress: true
|
|
64
|
+
|
|
65
|
+
"@playwright/mcp":
|
|
66
|
+
tool: browser
|
|
67
|
+
actions: [read, send]
|
|
68
|
+
data_classification: public
|
|
69
|
+
untrusted_input: true
|
|
70
|
+
egress: true
|
|
71
|
+
|
|
72
|
+
"@wonderwhy-er/desktop-commander":
|
|
73
|
+
tool: shell
|
|
74
|
+
actions: [read, write, delete, execute]
|
|
75
|
+
data_classification: confidential
|
|
76
|
+
|
|
77
|
+
"mcp-shell-server":
|
|
78
|
+
tool: shell
|
|
79
|
+
actions: [execute]
|
|
80
|
+
data_classification: confidential
|
|
81
|
+
|
|
82
|
+
"mcp-server-git":
|
|
83
|
+
tool: git
|
|
84
|
+
aliases: [mcp/git]
|
|
85
|
+
actions: [read, write] # git_add, git_commit, git_reset, git_checkout, git_create_branch
|
|
86
|
+
data_classification: confidential
|
|
87
|
+
resource_from: paths
|
|
88
|
+
|
|
89
|
+
"@modelcontextprotocol/server-memory":
|
|
90
|
+
tool: memory
|
|
91
|
+
aliases: [mcp/memory]
|
|
92
|
+
actions: [read, write]
|
|
93
|
+
data_classification: internal
|
|
94
|
+
|
|
95
|
+
# Remote (HTTP/SSE) MCP servers, matched on hostname.
|
|
96
|
+
remote_hosts:
|
|
97
|
+
"api.githubcopilot.com":
|
|
98
|
+
tool: github
|
|
99
|
+
actions: [read, write]
|
|
100
|
+
data_classification: confidential
|
|
101
|
+
untrusted_input: true
|
|
102
|
+
egress: true
|
|
@@ -0,0 +1,197 @@
|
|
|
1
|
+
"""Access review checks. Each function takes one agent and the review date and returns
|
|
2
|
+
findings; an empty list means the control is satisfied for that agent."""
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import re
|
|
6
|
+
from datetime import date
|
|
7
|
+
from pathlib import Path
|
|
8
|
+
from typing import Callable
|
|
9
|
+
|
|
10
|
+
import yaml
|
|
11
|
+
|
|
12
|
+
from .model import SENSITIVE_DATA, Agent, Finding
|
|
13
|
+
|
|
14
|
+
CONTROLS = yaml.safe_load((Path(__file__).parent / 'controls.yaml').read_text(encoding='utf-8'))['controls']
|
|
15
|
+
|
|
16
|
+
RECERTIFY_DAYS = 90
|
|
17
|
+
ROTATE_DAYS = 90
|
|
18
|
+
DORMANT_DAYS = 90
|
|
19
|
+
|
|
20
|
+
# Filesystem roots and whole home directories: an agent with these can read SSH keys,
|
|
21
|
+
# browser profiles and cloud credentials.
|
|
22
|
+
BROAD_PATH = re.compile(r'^(/|~/?|/(Users|home)/[^/]+/?|[A-Za-z]:/?|[A-Za-z]:/Users/[^/]+/?)$', re.I)
|
|
23
|
+
IS_PATH = re.compile(r'^([A-Za-z]:|[/~.\\])')
|
|
24
|
+
# Wildcards, admin scopes, GitHub's full-control "repo" scope and tenant-wide Microsoft Graph "*.All" scopes.
|
|
25
|
+
BROAD_SCOPE = re.compile(r'^(\*|.*:\*|admin(:.*)?|.*:admin|repo|full_access|all|.*\.All)$', re.I)
|
|
26
|
+
|
|
27
|
+
CheckFn = Callable[[Agent, date], list[Finding]]
|
|
28
|
+
REGISTRY: dict[str, CheckFn] = {}
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
def check(check_id: str):
|
|
32
|
+
def register(fn: CheckFn) -> CheckFn:
|
|
33
|
+
REGISTRY[check_id] = fn
|
|
34
|
+
return fn
|
|
35
|
+
return register
|
|
36
|
+
|
|
37
|
+
|
|
38
|
+
def run_all(agent: Agent, as_of: date) -> list[Finding]:
|
|
39
|
+
return [f for cid in sorted(REGISTRY) for f in REGISTRY[cid](agent, as_of)]
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
@check('AAR-01')
|
|
43
|
+
def owner(agent: Agent, as_of: date) -> list[Finding]:
|
|
44
|
+
if agent.owner:
|
|
45
|
+
return []
|
|
46
|
+
return [Finding('AAR-01', 'high', agent.id,
|
|
47
|
+
'No accountable human owner is recorded for this agent.',
|
|
48
|
+
'Assign an owner who answers for what the agent does, or decommission it.')]
|
|
49
|
+
|
|
50
|
+
|
|
51
|
+
@check('AAR-02')
|
|
52
|
+
def approval(agent: Agent, as_of: date) -> list[Finding]:
|
|
53
|
+
if not agent.approved_by or not agent.approved_on:
|
|
54
|
+
return [Finding('AAR-02', 'high', agent.id,
|
|
55
|
+
'Agent access has no recorded approval.',
|
|
56
|
+
'Route the agent through access approval before its next use.')]
|
|
57
|
+
age = (as_of - agent.approved_on).days
|
|
58
|
+
if age > RECERTIFY_DAYS:
|
|
59
|
+
return [Finding('AAR-02', 'medium', agent.id,
|
|
60
|
+
f'Access was last approved {age} days ago by {agent.approved_by} '
|
|
61
|
+
f'(limit {RECERTIFY_DAYS}).',
|
|
62
|
+
'Recertify: the owner confirms each tool below is still needed.')]
|
|
63
|
+
return []
|
|
64
|
+
|
|
65
|
+
|
|
66
|
+
@check('AAR-03')
|
|
67
|
+
def human_in_the_loop(agent: Agent, as_of: date) -> list[Finding]:
|
|
68
|
+
out = []
|
|
69
|
+
for g in agent.grants:
|
|
70
|
+
priv = g.privileged - {'execute'} # execute is covered by AAR-05
|
|
71
|
+
if not priv or g.requires_approval:
|
|
72
|
+
continue
|
|
73
|
+
severe = bool(priv & {'delete', 'admin'}) or g.data_classification in SENSITIVE_DATA
|
|
74
|
+
out.append(Finding('AAR-03', 'high' if severe else 'medium', agent.id,
|
|
75
|
+
f'{g.tool} can {" / ".join(sorted(priv))} {g.data_classification} data '
|
|
76
|
+
f'without a human approving each action.',
|
|
77
|
+
'Require human confirmation for these actions, or reduce the tool to read-only.',
|
|
78
|
+
tool=g.tool))
|
|
79
|
+
return out
|
|
80
|
+
|
|
81
|
+
|
|
82
|
+
@check('AAR-04')
|
|
83
|
+
def least_privilege(agent: Agent, as_of: date) -> list[Finding]:
|
|
84
|
+
out = []
|
|
85
|
+
for g in agent.grants:
|
|
86
|
+
broad = [s for s in g.scopes
|
|
87
|
+
if (BROAD_PATH.match(s.replace('\\', '/')) if IS_PATH.match(s) else BROAD_SCOPE.match(s))]
|
|
88
|
+
if 'admin' in g.actions:
|
|
89
|
+
broad.append('admin action')
|
|
90
|
+
if broad:
|
|
91
|
+
out.append(Finding('AAR-04', 'high', agent.id,
|
|
92
|
+
f'Over-broad access on {g.tool}: {", ".join(broad)}.',
|
|
93
|
+
'Narrow the grant to the specific directories, repositories or scopes '
|
|
94
|
+
'the agent needs.', tool=g.tool))
|
|
95
|
+
return out
|
|
96
|
+
|
|
97
|
+
|
|
98
|
+
@check('AAR-05')
|
|
99
|
+
def sandboxed_execution(agent: Agent, as_of: date) -> list[Finding]:
|
|
100
|
+
return [Finding('AAR-05', 'high', agent.id,
|
|
101
|
+
f'{g.tool} can execute arbitrary commands on the host without a sandbox.',
|
|
102
|
+
'Run the tool in a container or VM with no host credentials mounted, '
|
|
103
|
+
'or remove it.', tool=g.tool)
|
|
104
|
+
for g in agent.grants if 'execute' in g.actions and not g.sandboxed]
|
|
105
|
+
|
|
106
|
+
|
|
107
|
+
@check('AAR-06')
|
|
108
|
+
def hardcoded_credentials(agent: Agent, as_of: date) -> list[Finding]:
|
|
109
|
+
return [Finding('AAR-06', 'high', agent.id,
|
|
110
|
+
f'Credential {c.name} is stored in plain text in the agent configuration.',
|
|
111
|
+
'Revoke and reissue it, then load it from a secret manager or environment reference.',
|
|
112
|
+
tool=c.name.split('.', 1)[0])
|
|
113
|
+
for c in agent.credentials if c.hardcoded]
|
|
114
|
+
|
|
115
|
+
|
|
116
|
+
@check('AAR-07')
|
|
117
|
+
def credential_rotation(agent: Agent, as_of: date) -> list[Finding]:
|
|
118
|
+
out = []
|
|
119
|
+
for c in agent.credentials:
|
|
120
|
+
if c.hardcoded:
|
|
121
|
+
continue # AAR-06 already requires reissuing it
|
|
122
|
+
if c.last_rotated is None:
|
|
123
|
+
out.append(Finding('AAR-07', 'low', agent.id,
|
|
124
|
+
f'No rotation date is recorded for {c.name}.',
|
|
125
|
+
'Record when the credential was issued so rotation can be evidenced.',
|
|
126
|
+
tool=c.name.split('.', 1)[0]))
|
|
127
|
+
elif (age := (as_of - c.last_rotated).days) > ROTATE_DAYS:
|
|
128
|
+
out.append(Finding('AAR-07', 'medium', agent.id,
|
|
129
|
+
f'{c.name} was last rotated {age} days ago (limit {ROTATE_DAYS}).',
|
|
130
|
+
'Rotate the credential.', tool=c.name.split('.', 1)[0]))
|
|
131
|
+
return out
|
|
132
|
+
|
|
133
|
+
|
|
134
|
+
@check('AAR-08')
|
|
135
|
+
def dormant_access(agent: Agent, as_of: date) -> list[Finding]:
|
|
136
|
+
if agent.grants and all(g.last_used is None for g in agent.grants):
|
|
137
|
+
return [Finding('AAR-08', 'low', agent.id,
|
|
138
|
+
'No tool usage is logged, so dormant access cannot be identified.',
|
|
139
|
+
'Log tool calls per agent so unused access can be found and removed.')]
|
|
140
|
+
return [Finding('AAR-08', 'medium', agent.id,
|
|
141
|
+
f'{g.tool} has not been used for {(as_of - g.last_used).days} days.',
|
|
142
|
+
'Revoke this tool; re-request it if it is needed again.', tool=g.tool)
|
|
143
|
+
for g in agent.grants
|
|
144
|
+
if g.last_used is not None and (as_of - g.last_used).days > DORMANT_DAYS]
|
|
145
|
+
|
|
146
|
+
|
|
147
|
+
@check('AAR-09')
|
|
148
|
+
def exfiltration_path(agent: Agent, as_of: date) -> list[Finding]:
|
|
149
|
+
"""Sensitive data + attacker-controlled input + a way out = one prompt injection away from a breach."""
|
|
150
|
+
sensitive = [g for g in agent.grants if g.data_classification in SENSITIVE_DATA]
|
|
151
|
+
untrusted = [g for g in agent.grants if g.untrusted_input and not g.requires_approval]
|
|
152
|
+
egress = [g for g in agent.grants if g.egress and not g.requires_approval]
|
|
153
|
+
if not (sensitive and untrusted and egress):
|
|
154
|
+
return []
|
|
155
|
+
names = lambda gs: ', '.join(sorted({g.tool for g in gs}))
|
|
156
|
+
return [Finding('AAR-09', 'high', agent.id,
|
|
157
|
+
f'Exfiltration path: reads sensitive data ({names(sensitive)}), ingests untrusted '
|
|
158
|
+
f'content ({names(untrusted)}) and can send data out ({names(egress)}) with no '
|
|
159
|
+
f'human approval. A prompt injection in the untrusted content could leak the data.',
|
|
160
|
+
'Break the chain: split the agent, remove one leg, or require approval on '
|
|
161
|
+
'every egress action.')]
|
|
162
|
+
|
|
163
|
+
|
|
164
|
+
@check('AAR-10')
|
|
165
|
+
def pinned_packages(agent: Agent, as_of: date) -> list[Finding]:
|
|
166
|
+
return [Finding('AAR-10', 'medium', agent.id,
|
|
167
|
+
f'{g.tool} runs {g.package} without a pinned version, so a new upstream release '
|
|
168
|
+
f'runs automatically.',
|
|
169
|
+
'Pin an exact version (npm/PyPI) or image digest and update it through change control.',
|
|
170
|
+
tool=g.tool)
|
|
171
|
+
for g in agent.grants if g.pinned is False]
|
|
172
|
+
|
|
173
|
+
|
|
174
|
+
@check('AAR-11')
|
|
175
|
+
def encrypted_transport(agent: Agent, as_of: date) -> list[Finding]:
|
|
176
|
+
out = []
|
|
177
|
+
for g in agent.grants:
|
|
178
|
+
if not g.endpoint or not g.endpoint.lower().startswith('http://'):
|
|
179
|
+
continue
|
|
180
|
+
host = re.sub(r'^http://([^/:]+).*$', r'\1', g.endpoint.lower())
|
|
181
|
+
if host in {'localhost', '127.0.0.1', '[::1]', '::1'}:
|
|
182
|
+
continue
|
|
183
|
+
out.append(Finding('AAR-11', 'high', agent.id,
|
|
184
|
+
f'{g.tool} connects to {g.endpoint} over unencrypted HTTP.',
|
|
185
|
+
'Use HTTPS so credentials and tool traffic are encrypted in transit.',
|
|
186
|
+
tool=g.tool))
|
|
187
|
+
return out
|
|
188
|
+
|
|
189
|
+
|
|
190
|
+
@check('AAR-12')
|
|
191
|
+
def capability_inventory(agent: Agent, as_of: date) -> list[Finding]:
|
|
192
|
+
return [Finding('AAR-12', 'medium', agent.id,
|
|
193
|
+
f'{g.tool} ({g.resource}) is not in the capability catalog, so its access '
|
|
194
|
+
f'cannot be assessed.',
|
|
195
|
+
'Document what the tool can read, write and send, and add it to catalog.yaml.',
|
|
196
|
+
tool=g.tool)
|
|
197
|
+
for g in agent.grants if not g.known]
|
|
@@ -0,0 +1,91 @@
|
|
|
1
|
+
# Control catalog. Each check is defined once and cross-walked to every framework it
|
|
2
|
+
# provides evidence for. Mappings are my own judgment; verify them against the official
|
|
3
|
+
# crosswalks before relying on them in an audit.
|
|
4
|
+
#
|
|
5
|
+
# Frameworks: NIST SP 800-53 Rev. 5, AICPA TSC 2017 (rev. 2022), NIST AI RMF 1.0,
|
|
6
|
+
# OWASP Top 10 for LLM Applications 2025.
|
|
7
|
+
|
|
8
|
+
controls:
|
|
9
|
+
AAR-01:
|
|
10
|
+
title: Every agent has an accountable human owner
|
|
11
|
+
nist_800_53: [AC-2]
|
|
12
|
+
soc2: [CC6.2]
|
|
13
|
+
nist_ai_rmf: [GOVERN 2.1]
|
|
14
|
+
owasp_llm: []
|
|
15
|
+
|
|
16
|
+
AAR-02:
|
|
17
|
+
title: Agent access is approved and recertified within 90 days
|
|
18
|
+
nist_800_53: [AC-2]
|
|
19
|
+
soc2: [CC6.2, CC6.3]
|
|
20
|
+
nist_ai_rmf: []
|
|
21
|
+
owasp_llm: []
|
|
22
|
+
|
|
23
|
+
AAR-03:
|
|
24
|
+
title: Privileged agent actions require human approval
|
|
25
|
+
nist_800_53: [AC-6]
|
|
26
|
+
soc2: [CC6.3]
|
|
27
|
+
nist_ai_rmf: [MAP 3.5]
|
|
28
|
+
owasp_llm: [LLM06]
|
|
29
|
+
|
|
30
|
+
AAR-04:
|
|
31
|
+
title: Tool scopes follow least privilege
|
|
32
|
+
nist_800_53: [AC-6]
|
|
33
|
+
soc2: [CC6.3]
|
|
34
|
+
nist_ai_rmf: []
|
|
35
|
+
owasp_llm: [LLM06]
|
|
36
|
+
|
|
37
|
+
AAR-05:
|
|
38
|
+
title: Code and shell execution is sandboxed
|
|
39
|
+
nist_800_53: [CM-7, AC-6]
|
|
40
|
+
soc2: []
|
|
41
|
+
nist_ai_rmf: []
|
|
42
|
+
owasp_llm: [LLM05, LLM06]
|
|
43
|
+
|
|
44
|
+
AAR-06:
|
|
45
|
+
title: No credentials are hardcoded in agent configuration
|
|
46
|
+
nist_800_53: [IA-5]
|
|
47
|
+
soc2: [CC6.1]
|
|
48
|
+
nist_ai_rmf: []
|
|
49
|
+
owasp_llm: []
|
|
50
|
+
|
|
51
|
+
AAR-07:
|
|
52
|
+
title: Agent credentials are rotated within 90 days
|
|
53
|
+
nist_800_53: [IA-5]
|
|
54
|
+
soc2: [CC6.1]
|
|
55
|
+
nist_ai_rmf: []
|
|
56
|
+
owasp_llm: []
|
|
57
|
+
|
|
58
|
+
AAR-08:
|
|
59
|
+
title: Dormant agent access is removed after 90 days
|
|
60
|
+
nist_800_53: [AC-2(3)]
|
|
61
|
+
soc2: [CC6.2]
|
|
62
|
+
nist_ai_rmf: []
|
|
63
|
+
owasp_llm: []
|
|
64
|
+
|
|
65
|
+
AAR-09:
|
|
66
|
+
title: No unmitigated data exfiltration path
|
|
67
|
+
nist_800_53: [AC-4]
|
|
68
|
+
soc2: []
|
|
69
|
+
nist_ai_rmf: [MEASURE 2.7]
|
|
70
|
+
owasp_llm: [LLM01, LLM02]
|
|
71
|
+
|
|
72
|
+
AAR-10:
|
|
73
|
+
title: Tool packages are pinned to a version
|
|
74
|
+
nist_800_53: [SR-3]
|
|
75
|
+
soc2: []
|
|
76
|
+
nist_ai_rmf: []
|
|
77
|
+
owasp_llm: [LLM03]
|
|
78
|
+
|
|
79
|
+
AAR-11:
|
|
80
|
+
title: Remote tools use encrypted transport
|
|
81
|
+
nist_800_53: [SC-8]
|
|
82
|
+
soc2: [CC6.7]
|
|
83
|
+
nist_ai_rmf: []
|
|
84
|
+
owasp_llm: []
|
|
85
|
+
|
|
86
|
+
AAR-12:
|
|
87
|
+
title: Every tool's capabilities are inventoried
|
|
88
|
+
nist_800_53: [CM-8]
|
|
89
|
+
soc2: []
|
|
90
|
+
nist_ai_rmf: [GOVERN 1.6]
|
|
91
|
+
owasp_llm: []
|
|
@@ -0,0 +1,94 @@
|
|
|
1
|
+
# Governed agent manifest: one record per production agent, maintained by its owner.
|
|
2
|
+
agents:
|
|
3
|
+
- id: support-copilot
|
|
4
|
+
name: Customer Support Copilot
|
|
5
|
+
framework: langchain
|
|
6
|
+
owner: priya.shah@example.com
|
|
7
|
+
approved_by: ai-review-board
|
|
8
|
+
approved_on: 2026-08-20
|
|
9
|
+
tools:
|
|
10
|
+
- name: zendesk
|
|
11
|
+
type: ticketing
|
|
12
|
+
resource: zendesk:tickets
|
|
13
|
+
actions: [read, write]
|
|
14
|
+
data_classification: confidential
|
|
15
|
+
untrusted_input: true # customers write ticket text
|
|
16
|
+
requires_approval: true # agent drafts, a human sends
|
|
17
|
+
last_used: 2026-10-11
|
|
18
|
+
- name: kb-search
|
|
19
|
+
type: knowledge-base
|
|
20
|
+
resource: confluence:space/SUPPORT
|
|
21
|
+
actions: [read]
|
|
22
|
+
data_classification: internal
|
|
23
|
+
last_used: 2026-10-11
|
|
24
|
+
credentials:
|
|
25
|
+
- name: ZENDESK_API_TOKEN
|
|
26
|
+
tool: zendesk
|
|
27
|
+
source: vault
|
|
28
|
+
last_rotated: 2026-08-01
|
|
29
|
+
|
|
30
|
+
- id: finance-ops-agent
|
|
31
|
+
name: Finance Ops Agent
|
|
32
|
+
framework: crewai
|
|
33
|
+
owner: marco.diaz@example.com
|
|
34
|
+
approved_by: cfo-office
|
|
35
|
+
approved_on: 2026-03-10
|
|
36
|
+
tools:
|
|
37
|
+
- name: netsuite
|
|
38
|
+
type: erp
|
|
39
|
+
resource: netsuite:vendor-bills
|
|
40
|
+
actions: [read, write]
|
|
41
|
+
data_classification: restricted
|
|
42
|
+
last_used: 2026-10-09
|
|
43
|
+
- name: outlook
|
|
44
|
+
type: email
|
|
45
|
+
resource: mailbox:ap@example.com
|
|
46
|
+
actions: [read, send]
|
|
47
|
+
data_classification: confidential
|
|
48
|
+
untrusted_input: true # vendors email invoices
|
|
49
|
+
egress: true
|
|
50
|
+
last_used: 2026-10-10
|
|
51
|
+
- name: sharepoint
|
|
52
|
+
type: document-store
|
|
53
|
+
resource: sharepoint:finance
|
|
54
|
+
actions: [read]
|
|
55
|
+
scopes: [Sites.Read.All]
|
|
56
|
+
data_classification: confidential
|
|
57
|
+
last_used: 2026-10-01
|
|
58
|
+
- name: expense-ocr
|
|
59
|
+
type: ocr
|
|
60
|
+
resource: ocr-service:receipts
|
|
61
|
+
actions: [read]
|
|
62
|
+
data_classification: confidential
|
|
63
|
+
last_used: 2026-05-01
|
|
64
|
+
credentials:
|
|
65
|
+
- name: NETSUITE_TOKEN
|
|
66
|
+
tool: netsuite
|
|
67
|
+
source: env
|
|
68
|
+
last_rotated: 2025-12-01
|
|
69
|
+
- name: GRAPH_CLIENT_SECRET
|
|
70
|
+
tool: sharepoint
|
|
71
|
+
source: vault
|
|
72
|
+
last_rotated: 2026-09-15
|
|
73
|
+
|
|
74
|
+
- id: devops-agent
|
|
75
|
+
name: DevOps Auto-Remediation Agent
|
|
76
|
+
framework: custom
|
|
77
|
+
tools:
|
|
78
|
+
- name: shell
|
|
79
|
+
type: shell
|
|
80
|
+
resource: build-runner-07
|
|
81
|
+
actions: [execute]
|
|
82
|
+
data_classification: confidential
|
|
83
|
+
- name: github
|
|
84
|
+
type: source-control
|
|
85
|
+
resource: github:acme-corp
|
|
86
|
+
actions: [read, write]
|
|
87
|
+
scopes: [repo]
|
|
88
|
+
data_classification: confidential
|
|
89
|
+
package: "@acme/github-tools"
|
|
90
|
+
pinned: false
|
|
91
|
+
credentials:
|
|
92
|
+
- name: GITHUB_TOKEN
|
|
93
|
+
tool: github
|
|
94
|
+
source: hardcoded
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
{
|
|
2
|
+
"mcpServers": {
|
|
3
|
+
"filesystem": {
|
|
4
|
+
"command": "npx",
|
|
5
|
+
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/dev"]
|
|
6
|
+
},
|
|
7
|
+
"github": {
|
|
8
|
+
"command": "docker",
|
|
9
|
+
"args": ["run", "-i", "--rm", "-e", "GITHUB_PERSONAL_ACCESS_TOKEN", "ghcr.io/github/github-mcp-server"],
|
|
10
|
+
"env": {"GITHUB_PERSONAL_ACCESS_TOKEN": "example-not-a-real-token-0001"}
|
|
11
|
+
},
|
|
12
|
+
"fetch": {
|
|
13
|
+
"command": "uvx",
|
|
14
|
+
"args": ["mcp-server-fetch"]
|
|
15
|
+
},
|
|
16
|
+
"customers-db": {
|
|
17
|
+
"command": "npx",
|
|
18
|
+
"args": ["-y", "@modelcontextprotocol/server-postgres@0.6.2", "postgresql://analyst:example-password@db.internal:5432/customers"]
|
|
19
|
+
},
|
|
20
|
+
"terminal": {
|
|
21
|
+
"command": "npx",
|
|
22
|
+
"args": ["-y", "@wonderwhy-er/desktop-commander"]
|
|
23
|
+
},
|
|
24
|
+
"internal-crm": {
|
|
25
|
+
"command": "python",
|
|
26
|
+
"args": ["/opt/tools/crm_server.py", "--api-key=example-crm-key"]
|
|
27
|
+
}
|
|
28
|
+
}
|
|
29
|
+
}
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
{
|
|
2
|
+
"servers": {
|
|
3
|
+
"github": {
|
|
4
|
+
"type": "http",
|
|
5
|
+
"url": "https://api.githubcopilot.com/mcp/",
|
|
6
|
+
"headers": {"Authorization": "Bearer ${input:github-token}"}
|
|
7
|
+
},
|
|
8
|
+
"jira": {
|
|
9
|
+
"type": "http",
|
|
10
|
+
"url": "http://mcp.tools.example.com/jira",
|
|
11
|
+
"headers": {"Authorization": "Bearer ${input:jira-token}"}
|
|
12
|
+
}
|
|
13
|
+
}
|
|
14
|
+
}
|
|
@@ -0,0 +1,66 @@
|
|
|
1
|
+
"""Normalized inventory model. Every input format (MCP configs, agent manifests) is
|
|
2
|
+
parsed into these classes so the checks never care where an agent came from."""
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
from dataclasses import dataclass, field
|
|
6
|
+
from datetime import date
|
|
7
|
+
|
|
8
|
+
# Actions that change state or move data. Anything outside {"read"} is privileged.
|
|
9
|
+
PRIVILEGED_ACTIONS = {'write', 'delete', 'send', 'execute', 'admin'}
|
|
10
|
+
SENSITIVE_DATA = {'confidential', 'restricted'}
|
|
11
|
+
SEVERITY_ORDER = {'high': 3, 'medium': 2, 'low': 1}
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
@dataclass
|
|
15
|
+
class Grant:
|
|
16
|
+
"""One tool or MCP server the agent can call, and what it can do with it."""
|
|
17
|
+
tool: str
|
|
18
|
+
resource: str
|
|
19
|
+
actions: set[str]
|
|
20
|
+
scopes: list[str] = field(default_factory=list)
|
|
21
|
+
data_classification: str = 'internal' # public | internal | confidential | restricted
|
|
22
|
+
untrusted_input: bool = False # reads content an outsider can write (web, tickets, email)
|
|
23
|
+
egress: bool = False # can send data outside the organization
|
|
24
|
+
requires_approval: bool = False # a human approves each privileged call
|
|
25
|
+
sandboxed: bool = False
|
|
26
|
+
last_used: date | None = None
|
|
27
|
+
package: str | None = None # npm / PyPI / container reference it runs from
|
|
28
|
+
pinned: bool | None = None # None = not a package (local code), so not assessable
|
|
29
|
+
endpoint: str | None = None # remote MCP URL
|
|
30
|
+
known: bool = True # False when capabilities could not be classified
|
|
31
|
+
category: str | None = None # capability profile from catalog.yaml (filesystem, shell, ...)
|
|
32
|
+
|
|
33
|
+
@property
|
|
34
|
+
def privileged(self) -> set[str]:
|
|
35
|
+
return self.actions & PRIVILEGED_ACTIONS
|
|
36
|
+
|
|
37
|
+
|
|
38
|
+
@dataclass
|
|
39
|
+
class Credential:
|
|
40
|
+
name: str
|
|
41
|
+
hardcoded: bool
|
|
42
|
+
last_rotated: date | None = None
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
@dataclass
|
|
46
|
+
class Agent:
|
|
47
|
+
id: str
|
|
48
|
+
name: str
|
|
49
|
+
source: str # file the agent was discovered in
|
|
50
|
+
source_type: str # mcp-config | agent-manifest
|
|
51
|
+
owner: str | None = None
|
|
52
|
+
approved_by: str | None = None
|
|
53
|
+
approved_on: date | None = None
|
|
54
|
+
grants: list[Grant] = field(default_factory=list)
|
|
55
|
+
credentials: list[Credential] = field(default_factory=list)
|
|
56
|
+
raw: dict = field(default_factory=dict) # redacted source record, kept as evidence
|
|
57
|
+
|
|
58
|
+
|
|
59
|
+
@dataclass
|
|
60
|
+
class Finding:
|
|
61
|
+
check_id: str
|
|
62
|
+
severity: str # high | medium | low
|
|
63
|
+
agent_id: str
|
|
64
|
+
message: str
|
|
65
|
+
recommendation: str
|
|
66
|
+
tool: str | None = None # None = applies to the whole agent
|