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.
@@ -0,0 +1,4 @@
1
+ """Access reviews for AI agents: inventory what each agent can reach, test it against
2
+ access controls, and produce audit-ready evidence."""
3
+
4
+ __version__ = '0.2.1'
@@ -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