Skip to content

Commit 26fda3b

Browse files
anandgupta42claude
anandgupta42
and
claude
authored
docs: add security FAQ (#44)
* docs: add security FAQ to reference section Covers the practical security questions — data privacy, credential handling, permission controls, network endpoints, telemetry, MCP server trust, Python engine isolation, air-gapped usage, team security, and AI-generated SQL safety. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * fix: direct vulnerability reports to security@altimate.ai, not public issues Aligns with SECURITY.md policy — vulnerabilities should be reported via private email, not public GitHub issues. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
1 parent 6ec6d3e commit 26fda3b

File tree

2 files changed

+184
-0
lines changed

2 files changed

+184
-0
lines changed

‎docs/docs/security-faq.md‎

Lines changed: 183 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,183 @@
1+
# Security FAQ
2+
3+
Answers to the most common security questions about running Altimate Code in your environment.
4+
5+
---
6+
7+
## Does Altimate Code send my data to external services?
8+
9+
Altimate Code sends prompts and context to the LLM provider you configure (Anthropic, OpenAI, Azure OpenAI, AWS Bedrock, etc.). **You choose the provider.** No data is sent anywhere else except optional [telemetry](#what-telemetry-is-collected), which contains no code, queries, or credentials.
10+
11+
If you use a self-hosted or VPC-deployed model (e.g., AWS Bedrock, Azure OpenAI), your data never leaves your cloud account.
12+
13+
## Can the AI read my database credentials?
14+
15+
Altimate Code needs database credentials to connect to your warehouse. Credentials are stored locally in your project's `altimate-code.json` or passed via environment variables. They are **never** included in telemetry, logged, or sent to any service other than your database.
16+
17+
!!! tip
18+
Prefer environment variables or your cloud provider's secret manager over hardcoding credentials in config files. Add `altimate-code.json` to `.gitignore` if it contains connection strings.
19+
20+
## What can the agent actually execute?
21+
22+
Altimate Code can read files, write files, and run shell commands — but only with your permission. The [permission system](configure/permissions.md) lets you control every tool:
23+
24+
| Level | Behavior |
25+
|-------|----------|
26+
| `"allow"` | Runs without confirmation |
27+
| `"ask"` | Prompts you before each use |
28+
| `"deny"` | Blocked entirely |
29+
30+
By default, destructive operations like `bash`, `write`, and `edit` require confirmation. You can further restrict specific commands:
31+
32+
```json
33+
{
34+
"permission": {
35+
"bash": {
36+
"dbt *": "allow",
37+
"git status": "allow",
38+
"DROP *": "deny",
39+
"rm *": "deny",
40+
"*": "ask"
41+
}
42+
}
43+
}
44+
```
45+
46+
## Can I prevent the agent from modifying production databases?
47+
48+
Yes. Use pattern-based permissions to deny destructive SQL:
49+
50+
```json
51+
{
52+
"permission": {
53+
"bash": {
54+
"DROP *": "deny",
55+
"DELETE *": "deny",
56+
"TRUNCATE *": "deny",
57+
"ALTER *": "deny",
58+
"*": "ask"
59+
}
60+
}
61+
}
62+
```
63+
64+
You can also configure per-agent permissions. For example, restrict the `analyst` agent to read-only:
65+
66+
```json
67+
{
68+
"agent": {
69+
"analyst": {
70+
"permission": {
71+
"write": "deny",
72+
"edit": "deny",
73+
"bash": {
74+
"SELECT *": "allow",
75+
"*": "deny"
76+
}
77+
}
78+
}
79+
}
80+
}
81+
```
82+
83+
## What network endpoints does Altimate Code contact?
84+
85+
| Destination | Purpose |
86+
|-------------|---------|
87+
| Your configured LLM provider | Model inference |
88+
| Your warehouse endpoints | Database queries |
89+
| `registry.npmjs.org` | Package updates |
90+
| `models.dev` | Model catalog (can be disabled) |
91+
| `eastus-8.in.applicationinsights.azure.com` | Telemetry (can be disabled) |
92+
93+
No other outbound connections are made. See the [Network reference](network.md) for proxy and firewall configuration.
94+
95+
## Can I run Altimate Code without internet access?
96+
97+
Yes, with constraints. You need:
98+
99+
1. **A locally accessible LLM** — self-hosted model or a provider reachable from your network
100+
2. **Model catalog disabled** — set `ALTIMATE_CLI_DISABLE_MODELS_FETCH=true` or provide a local models file
101+
3. **Telemetry disabled** — set `ALTIMATE_TELEMETRY_DISABLED=true`
102+
103+
```bash
104+
export ALTIMATE_CLI_DISABLE_MODELS_FETCH=true
105+
export ALTIMATE_TELEMETRY_DISABLED=true
106+
export ALTIMATE_CLI_MODELS_PATH=/path/to/models.json
107+
```
108+
109+
## What telemetry is collected?
110+
111+
Anonymous usage telemetry — event names, token counts, timing, and error types. **Never** code, queries, credentials, file paths, or prompt content. See the full [Telemetry reference](configure/telemetry.md) for the complete event list.
112+
113+
Disable telemetry entirely:
114+
115+
```json
116+
{
117+
"telemetry": {
118+
"disabled": true
119+
}
120+
}
121+
```
122+
123+
Or via environment variable:
124+
125+
```bash
126+
export ALTIMATE_TELEMETRY_DISABLED=true
127+
```
128+
129+
## Are MCP servers a security risk?
130+
131+
MCP (Model Context Protocol) servers extend Altimate Code with additional tools. They run as local subprocesses or connect via SSE/HTTP. Security considerations:
132+
133+
- **Only install MCP servers you trust.** They run with the same permissions as your user account.
134+
- **MCP servers can access your filesystem and network.** Review what a server does before adding it.
135+
- **MCP tool calls go through the permission system.** You can set MCP tools to `"ask"` or `"deny"` like any other tool.
136+
137+
!!! warning
138+
Third-party MCP servers are not reviewed or audited by Altimate. Treat them like any other third-party dependency — review the source, check for updates, and limit their access.
139+
140+
## How does the Python engine work? Is it safe?
141+
142+
The Python engine (`altimate_engine`) runs as a local subprocess, communicating with the CLI over JSON-RPC via stdio. It:
143+
144+
- Runs under your user account with your permissions
145+
- Has no network access beyond what your warehouse connections require
146+
- Restarts automatically if it crashes (max 2 restarts)
147+
- Times out after 30 seconds per call
148+
149+
The engine is not exposed on any network port — it only communicates through stdin/stdout pipes with the parent CLI process.
150+
151+
## Does Altimate Code store conversation history?
152+
153+
Conversation context lives in memory during your session. Altimate Code does not persist conversation history to disk or send it to any service. When you end a session, the context is gone.
154+
155+
!!! note
156+
Your LLM provider may have its own data retention policies. Check your provider's terms to understand how they handle API requests.
157+
158+
## How do I secure Altimate Code in a team environment?
159+
160+
1. **Use project-level config** — Place `altimate-code.json` in your project root with appropriate permission defaults. This ensures consistent security settings across the team.
161+
162+
2. **Restrict dangerous operations** — Deny destructive SQL and shell commands at the project level so individual users can't accidentally bypass them.
163+
164+
3. **Use environment variables for secrets** — Never commit credentials. Use `ALTIMATE_CLI_PYTHON`, warehouse connection env vars, and your cloud provider's secret management.
165+
166+
4. **Review MCP servers** — Maintain a list of approved MCP servers. Don't let individual developers add arbitrary servers to shared configurations.
167+
168+
5. **Lock down agent permissions** — Give each agent only the permissions it needs. The `analyst` agent doesn't need `write` access. The `builder` agent doesn't need `DROP` permissions.
169+
170+
## Can AI-generated SQL damage my database?
171+
172+
Altimate Code generates SQL based on your instructions and schema context. Like any generated code, it should be reviewed before execution. The permission system defaults to `"ask"` for shell commands, so you'll see every query before it runs.
173+
174+
For additional safety:
175+
176+
- Use a **read-only database user** for exploration and analysis
177+
- **Deny destructive DDL/DML** via pattern-based permissions
178+
- Run against a **staging environment** before production
179+
- Use the `analyst` agent with restricted permissions for ad-hoc queries
180+
181+
## Where should I report security vulnerabilities?
182+
183+
**Do not open public GitHub issues for security vulnerabilities.** Instead, email **security@altimate.ai** with a description, reproduction steps, and your severity assessment. You'll receive acknowledgment within 48 hours. See the full [Security Policy](https://github.com/AltimateAI/altimate-code/blob/main/SECURITY.md) for details.

‎docs/mkdocs.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -107,6 +107,7 @@ nav:
107107
- Plugins: develop/plugins.md
108108
- Ecosystem: develop/ecosystem.md
109109
- Reference:
110+
- Security FAQ: security-faq.md
110111
- Network: network.md
111112
- Troubleshooting: troubleshooting.md
112113
- Windows / WSL: windows-wsl.md

0 commit comments

Comments
 (0)