> ## Documentation Index
> Fetch the complete documentation index at: https://withcoral.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Security model

> Coral's intended threat model for the current release.

Coral is designed as a local data-access layer for a trusted user and the agents
or scripts that user chooses to run. It does not send your source configuration,
usage history, or query results to a Coral-hosted service. Source credentials
are used locally and sent to the upstream providers you configure when a query
requires them.

## Intended threat model

This release is intended for single-user local use:

* You install and run the `coral` binary on your own macOS, Linux, or x86\_64
  Windows machine.
* You choose which source specs to install, which credentials to provide, and
  which MCP clients or scripts may call Coral.
* Coral stores configuration under the local Coral config directory, which
  defaults to the platform config directory and can be changed with
  `CORAL_CONFIG_DIR`. Source secrets default to OS credential storage when the
  local keychain is usable, with plaintext file storage available as fallback.
* CLI and MCP queries run through the same local runtime. The internal gRPC
  server binds to loopback, and the MCP server uses stdio transport.

Coral reduces data exposure by keeping execution local and by exposing a narrow
MCP surface: `sql`, `list_catalog`, `search_catalog`, `describe_table`,
`list_columns`, optional `feedback`, `coral://guide`, and `coral://tables`.
MCP tool and resource metadata can include installed source/schema names so
clients can route source-specific requests to Coral during discovery.
Secret values are not returned through `coral.inputs`; secret rows show only
whether a value is configured.

## What Coral protects against

Coral's current protections are aimed at accidental exposure within that local
trust boundary:

* Source secrets are stored separately from non-secret source variables and are
  never written into `config.toml`.
* By default, sources use the operating-system credential store when Coral
  can successfully write, read, and delete a probe item. On macOS this uses
  Keychain; on Windows, Credential Manager; on Linux, Secret Service.
* If keychain probing fails in `auto` mode, Coral stores source secrets in
  plaintext local files and reports the route as `file (plaintext)` in source
  output.
* State files written by Coral use private file permissions on Unix systems.
  On Windows, Coral stores local state under
  `%APPDATA%\withcoral\coral\config` by default and relies on the user's
  Windows profile ACLs as the local trust boundary.
* SQL execution is configured as read-only: DDL, DML, and multiple statements
  are disabled.
* Source and workspace names are validated before they are used in local state
  paths.
* MCP clients can query installed sources, but they do not receive raw stored
  secret values through the discovery tables or resources.

## Secret storage configuration

Coral reads the credential storage preference from `config.toml`:

```toml theme={"theme":{"light":"github-light","dark":"github-dark"}}
[credentials]
storage = "auto"
```

Supported values:

| Value      | Behavior                                                                              |
| ---------- | ------------------------------------------------------------------------------------- |
| `auto`     | Default. Use keychain when the probe succeeds; otherwise use plaintext file storage.  |
| `keychain` | Require OS credential storage. If unavailable, source installation fails.             |
| `file`     | Store source secrets in plaintext `secrets.env` files under Coral's config directory. |

<Note>
  Changing the global preference does not rewrite existing credentials. To update those, remove and re-add the source you want to update.
</Note>

## What you still need to trust

Coral is not a sandbox for untrusted agents, source specs, or credentials.
If you give an unsandboxed agent permission to run as your user, that agent may
already be able to read local files your OS account can read, such as shell
config, project files, or SSH configuration. Coral adds access to the sources
you configure; it does not make an otherwise untrusted local agent safe.

* A connected MCP client can ask Coral to query any source you have installed.
* A source token can access whatever the upstream provider allows for that
  token, so prefer read-only and least-privilege credentials.
* A custom source spec can direct Coral to make HTTP requests or read local file
  locations declared by that spec. Only install source specs you trust.
* Anyone who can control your user account should be treated as able to use the
  configured sources. If a source uses file-backed secret storage, anyone who
  can read your local Coral config directory should also be treated as able to
  read its stored source secrets.
* Coral does not attempt to protect against a compromised machine, compromised
  MCP client, malicious shell environment, or malicious upstream API response.

## Practical guidance

* Scope provider tokens to the minimum data your workflow needs.
* Put Coral's config directory on a local disk protected by your operating
  system account controls.
* Use `coral source list` or `coral source info <NAME>` to inspect whether a
  source uses `keychain` or `file (plaintext)` secret storage.
* Review custom source specs before installing them, especially `base_url`,
  `auth`, and file `location` fields.
* Configure `coral mcp-stdio` only in MCP clients you are comfortable allowing
  to query your installed sources.

Report suspected vulnerabilities privately through the project's
[security policy](https://github.com/withcoral/coral/blob/main/SECURITY.md).