Merge pull request #777 from prometheus/sm

Document our security model

content/docs/alerting/configuration.md

@@ -43,7 +43,9 @@ Generic placeholders are defined as follows:
 * `<filepath>`: a valid path in the current working directory
 * `<boolean>`: a boolean that can take the values `true` or `false`
 * `<string>`: a regular string
+* `<secret>`: a regular string that is a secret, such as a password
 * `<tmpl_string>`: a string which is template-expanded before usage
+* `<tmpl_secret>`: a string which is template-expanded before usage that is a secret
 
 The other placeholders are specified separately.
 
@@ -66,8 +68,8 @@ global:
   [ smtp_smarthost: <string> ]
   # SMTP authentication information.
   [ smtp_auth_username: <string> ]
-  [ smtp_auth_password: <string> ]
-  [ smtp_auth_secret: <string> ]
+  [ smtp_auth_password: <secret> ]
+  [ smtp_auth_secret: <secret> ]
   [ smtp_auth_identity: <string> ]
   # The default SMTP TLS requirement.
   [ smtp_require_tls: <bool> | default = true ]
@@ -78,7 +80,7 @@ global:
   [ pagerduty_url: <string> | default = "https://events.pagerduty.com/generic/2010-04-15/create_event.json" ]
   [ opsgenie_api_host: <string> | default = "https://api.opsgenie.com/" ]
   [ hipchat_url: <string> | default = "https://api.hipchat.com/" ]
-  [ hipchat_auth_token: <string> ]
+  [ hipchat_auth_token: <secret> ]
 
 # Files from which custom notification template definitions are read.
 # The last component may use a wildcard matcher, e.g. 'templates/*.tmpl'.
@@ -249,8 +251,8 @@ to: <tmpl_string>
 [ smarthost: <string> | default = global.smtp_smarthost ]
 # SMTP authentication information.
 [ auth_username: <string> ]
-[ auth_password: <string> ]
-[ auth_secret: <string> ]
+[ auth_password: <secret> ]
+[ auth_secret: <secret> ]
 [ auth_identity: <string> ]
 
 [ require_tls: <bool> | default = global.smtp_require_tls ]
@@ -274,7 +276,7 @@ HipChat notifications use a [Build Your Own](https://confluence.atlassian.com/hc
 # The HipChat Room ID.
 room_id: <tmpl_string>
 # The auth token.
-[ auth_token: <string> | default = global.hipchat_auth_token ]
+[ auth_token: <secret> | default = global.hipchat_auth_token ]
 # The URL to send API requests to.
 [ api_url: <string> | default = global.hipchat_url ]
 
@@ -300,7 +302,7 @@ PagerDuty notifications are sent via the [PagerDuty API](https://developer.pager
 [ send_resolved: <boolean> | default = true ]
 
 # The PagerDuty service key.
-service_key: <tmpl_string>
+service_key: <tmpl_secret>
 # The URL to send API requests to
 [ url: <string> | default = global.pagerduty_url ]
 
@@ -328,10 +330,10 @@ Pushover notifications are sent via the [Pushover API](https://pushover.net/api)
 
 ```
 # The recipient user’s user key.
-user_key: <string>
+user_key: <secret>
 
 # Your registered application’s API token, see https://pushover.net/apps
-token: <string>
+token: <secret>
 
 # Notification title.
 [ title: <tmpl_string> | default = '{{ template "pushover.default.title" . }}' ]
@@ -363,7 +365,7 @@ Slack notifications are sent via [Slack webhooks](https://api.slack.com/incoming
 [ send_resolved: <boolean> | default = false ]
 
 # The Slack webhook URL.
-[ api_url: <string> | default = global.slack_api_url ]
+[ api_url: <secret> | default = global.slack_api_url ]
 
 # The channel or user to send notifications to.
 channel: <tmpl_string>
@@ -390,7 +392,7 @@ OpsGenie notifications are sent via the [OpsGenie API](https://www.opsgenie.com/
 [ send_resolved: <boolean> | default = true ]
 
 # The API key to use when talking to the OpsGenie API.
-api_key: <string>
+api_key: <secret>
 
 # The host to send OpsGenie API requests to.
 [ api_host: <string> | default = global.opsgenie_api_host ]
@@ -415,7 +417,7 @@ VictorOps notifications are sent out via the [VictorOps API](https://help.victor
 
 ```
 # The API key to use when talking to the VictorOps API.
-api_key: <string>
+api_key: <secret>
 
 # The VictorOps API URL.
 [ api_url: <string> | default = global.victorops_api_url ]

content/docs/operating/configuration.md

@@ -42,6 +42,7 @@ Generic placeholders are defined as follows:
 * `<path>`: a valid URL path
 * `<scheme>`: a string that can take the values `http` or `https`
 * `<string>`: a regular string
+* `<secret>`: a regular string that is a secret, such as a password
 
 The other placeholders are specified separately.
 
@@ -147,11 +148,11 @@ params:
 # configured username and password.
 basic_auth:
   [ username: <string> ]
-  [ password: <string> ]
+  [ password: <secret> ]
 
 # Sets the `Authorization` header on every scrape request with
 # the configured bearer token. It is mutually exclusive with `bearer_token_file`.
-[ bearer_token: <string> ]
+[ bearer_token: <secret> ]
 
 # Sets the `Authorization` header on every scrape request with the bearer token
 # read from the configured file. It is mutually exclusive with `bearer_token`.
@@ -279,7 +280,7 @@ tenant_id: <string>
 # The client ID.
 client_id: <string>
 # The client secret.
-client_secret: <string>
+client_secret: <secret>
 
 # Refresh interval to re-read the instance list.
 [ refresh_interval: <duration> | default = 300s ]
@@ -309,11 +310,11 @@ The following meta labels are available on targets during [relabeling](#relabel_
 # The information to access the Consul API. It is to be defined
 # as the Consul documentation requires.
 server: <host>
-[ token: <string> ]
+[ token: <secret> ]
 [ datacenter: <string> ]
 [ scheme: <string> ]
 [ username: <string> ]
-[ password: <string> ]
+[ password: <secret> ]
 
 # A list of services for which targets are retrieved. If omitted, all services
 # are scraped.
@@ -392,7 +393,7 @@ region: <string>
 # The AWS API keys. If blank, the environment variables `AWS_ACCESS_KEY_ID`
 # and `AWS_SECRET_ACCESS_KEY` are used.
 [ access_key: <string> ]
-[ secret_key: <string> ]
+[ secret_key: <secret> ]
 # Named AWS profile used to connect to the API.
 [ profile: <string> ]
 
@@ -444,7 +445,7 @@ region: <string>
 
 # password for the Identity V2 and V3 APIs. Consult with your provider's
 # control panel to discover your account's preferred method of authentication.
-[ password: <string> ]
+[ password: <secret> ]
 
 # At most one of domain_id and domain_name must be provided if using username
 # with Identity V3. Otherwise, either are optional.
@@ -674,10 +675,10 @@ role: <role>
 # Optional HTTP basic authentication information.
 basic_auth:
   [ username: <string> ]
-  [ password: <string> ]
+  [ password: <secret> ]
 
 # Optional bearer token authentication information.
-[ bearer_token: <string> ]
+[ bearer_token: <secret> ]
 
 # Optional bearer token file authentication information.
 [ bearer_token_file: <filename> ]
@@ -728,7 +729,7 @@ servers:
 
 # Optional bearer token authentication information.
 # It is mutually exclusive with `bearer_token_file`.
-[ bearer_token: <string> ]
+[ bearer_token: <secret> ]
 
 # Optional bearer token file authentication information.
 # It is mutually exclusive with `bearer_token`.

content/docs/operating/security.md

+---
+title: Security
+sort_rank: 4
+---
+
+# Security Model
+
+Prometheus is a sophisticated system with many components and many integrations
+with other systems. It can be deployed in a variety of trusted and untrusted
+environments.
+
+This page describes the general security assumptions of Prometheus and the
+attack vectors that some configurations may enable.
+
+As with any complex systems it is not possible to gaurantee that there are no
+bugs. If you find a security bug, please file it in the issue tracker of the
+relevant component.
+
+### Prometheus
+
+It is presumed that untrusted users have access to the Prometheus HTTP endpoint
+and logs. They have access to all time series information contained in the
+database, plus a variety of operational/debugging information.
+
+It is also presumed that only trusted users have the ability to change the
+command line, configuration file, rule files and other aspects of the runtime
+enviroment of Prometheus and other components.
+
+Which targets Prometheus scrapes, how often and with what other settings is
+determined entirely via the configuration file. The administrator may
+decide to use information from service discovery systems, which combined with
+relabelling may grant some of this control to anyone who can modify data in
+that service discovery system.
+
+Scraped targets may be run by untrusted users. It should not by default be
+possible for a target to expose data that impersonates a different target.  The
+`honor_labels` option removes this protection, as can certain relabelling
+setups.
+
+At present the HTTP API grants the ability to reload configuration files,
+shutdown the server, and delete time series. This will be [changed in Prometheus
+2.0](https://github.com/prometheus/prometheus/issues/2173).
+
+The remote read feature allows anyone with HTTP access to send queries to the
+remote read endpoint. If for example the PromQL queries were ending up directly
+run against a relational database, then anyone with the ability to send queries
+to Prometheus (such as via Grafana) can run arbitrary SQL against that
+database.
+
+## Alertmanager
+
+Any user with access to the Alertmanager HTTP endpoint has access to its data.
+They can create and resolve alerts. They can create, modify and delete
+silences.
+
+Where notifications are sent to is determined by the configuration file. With
+certain templating setups it is possible for notifications to end up at an
+alert-defined destination. For example if notifications use an alert label as
+the destination email address, anyone who can send alerts to the Alertmanager
+can send notifications to any email address.
+
+## Pushgateway
+
+Any user with access to the Pushgateway HTTP endpoint can create, modify and
+delete the metrics contained within. As the Pushgateway is usually scraped with
+`honor_labels` enabled, this means anyone with access to the Pushgateway can
+create any time series in Prometheus.
+
+## Exporters
+
+Exporters generally only talk to one configured instance with a preset set of
+commands/requests, which cannot be expanded via their HTTP endpoint.
+
+There are also exporters such as the SNMP and Blackbox exporters that take
+their targets from URL parameters. Thus anyone with HTTP access to these
+exporters can make them send requests to arbitrary endpoints. As they also
+support client-side authentication, this could lead to a leak of secrets such
+as HTTP Basic Auth passwords or SNMP community strings. Challenge-response
+authentication mechanisms such as TLS are not affected by this.
+
+## Client Libraries
+
+Client libaries are intended to be included in users' applications.
+
+If using a client-library-provided HTTP handler, it should not be possible for
+malicious requests that reach that handler to cause issues beyond those
+resulting from additional load and failed scrapes.
+
+## Authentication/Authorisation/Encryption
+
+Prometheus and its components do not provide any server-side
+authentication, authorisation or encryption. If you require this, it is
+recommended to use a reverse proxy.
+
+Various Prometheus components support client-side authentication and
+encryption. If TLS client support is offered, there is often also an option
+called `insecure_skip_verify` which skips SSL verification.
+
+## Secrets
+
+Non-secret information or fields may be available via the HTTP API and/or logs.
+
+In Prometheus, metadata retrieved from service discovery is not considered
+secret. Throughout the Prometheus system, metrics are not considered secret.
+
+Fields containing secrets in configuration files (marked explicitly as such in
+the documentation) will not be exposed in logs or via the HTTP API. Secrets
+should not be placed in other configuration fields, as it is common for
+components to expose their configuration over their HTTP endpoint.
+
+Secrets from other sources used by dependencies (e.g. the `AWS_SECRET_KEY`
+enviroment vabiable as used by EC2 service discovery) may end up exposed due to
+code outside of our control or due to functionality that happens to expose
+wherever it is stored.
+
+## Denial of Service
+
+There are some mitigations in place for excess load or expensive queries.
+However, if too many or too expensive queries/metrics are provided components
+will fall over. It is more likely that a component will be accidentally taken
+out by a trusted user than by malicious action.
+
+It is the responsibility of the the user to ensure they provide components with
+sufficient resources including CPU, RAM, disk space, IOPS, file descriptors,
+and bandwidth.
+
+It is recommended to monitor all components for failure, and to have them
+automatically restart on failure.
+
+## Libraries
+
+This document considers vanilla binaries built from the stock source code.
+Information presented here does not apply if you modify Prometheus source code,
+or use Prometheus internals (beyond the official client library APIs) in your
+own code.
+
+## Build Process
+
+The build pipeline for Prometheus runs on third-party providers to which many
+members of the Prometheus development team and the staff of those providers
+have access. If you are concerned about the exact provenance of your binaries,
+it is recommended to build them yourself rather than relying on the
+pre-built binaries provided by the project.