Redesign and consolidate the Security section

[knz]

Raphael 'kena' Poss (knz) commented:

This issue consolidates seemingly unrelated SIAM projects into a single action plan.

Table of contents:

• Linked issues
• Current doc structure and problems
• Proposed structure

Linked issues

The existing issues in the repo can be grouped in broad themes, as follows. Note that these do not necessarily aim to translate to specific sections in the docs. See the next sections for that.

• Security architecture

  • Underscore how dangerous "Insecure" mode Underscore how dangerous "Insecure" mode #6574
  • Add support for self-service IAM Add support for self-service IAM #6485
  • Update security concepts Update security concepts #6565
  • Create tutorial / webinar on how to set up a secure cluster in the cloud Create tutorial / webinar on how to set up a secure cluster in the cloud #5230

• Public relations wrt security

  • Create public-facing security policy doc Create public-facing security policy doc #5206

• Non-repudiation

  • EXPERIMENTAL_AUDIT Doc Update EXPERIMENTAL_AUDIT Doc Update #5444
  • cli,log: change the default file permissions cli,log: change the default file permissions #6583
  • cli,log: change the default file permissions cli,log: change the default file permissions #6578

• Tamper protection

  • Improve the Encryption at Rest docs Rationalize encryption docs across SH and CC Dedicated #5154

• Authentication

  • Rule-based configuration

    • Improved support for PostgreSQL's Host-Based Authentication (HBA) configuration language Improved support for PostgreSQL's Host-Based Authentication (HBA) configuration language #6805
    • hba: stricter parsing and better pretty-printing hba: stricter parsing and better pretty-printing #6581

  • TLS client certs

    • Create Security Certificates Doc Update Create Security Certificates Doc Update #2923
    • Create Security Certificates Doc Update Remove most mentions of public CAs from Create Security Certificates #5059
    • cli: add --cert-principal-map to cert list command cli: add --cert-principal-map to cert list command #7650
    • cli: add --cert-principal-map to client commands cli: add --cert-principal-map to client commands #7653
    • release-20.1: cli: add --cert-principal-map to client commands release-20.1: cli: add --cert-principal-map to client commands #7424
    • Cert naming convention for root user Cert naming convention for root user #7538

  • Kerberos / GSSAPI

    • Add GSSAPI auth and host-based auth configuration to security overview doc Add GSSAPI auth and host-based auth configuration to security overview doc #4656
    • Document 1way trust pattern so CRDB admins can administer service accounts separately from domain accounts Document 1way trust pattern so CRDB admins can administer service accounts separately from domain accounts #5765
    • Update language around SPN in Kerberos/GSSAPI docs Update language around SPN in Kerberos/GSSAPI docs #7530
    • Update Kerberos docs Update Kerberos docs #7364

  • Admin UI authn

    • cli: new command auth-session {login,logout,list} cli: new command auth-session {login,logout,list} #6631
    • release-19.2: cli: new command `auth-session {login,logout,lis… Document the auth-session CLI commands #6466

• Authorization

  • Establish equivalency between the keywords ROLE and USER Establish equivalency between the keywords ROLE and USER #7063
  • Adjust SQL diagram to show ROLE as an alias for USER. Adjust SQL diagram to show ROLE as an alias for USER. #7022

Current doc structure and problems

The current security docs are currently structured as follows:

• Overview

  • The page should start with explaining the security model. It does not.
  • There's a random notice about insecure mode at the top. The page does not even explain what "insecure" means.
  • There's a section called "Security overview". However it does not present an overview. There should be an overview instead.
  • The "overview" section presents instead commonly-known terms in a random order. These are generic term definitions from the industry and not specific to CockroachDB. These definitions should move outside of the head page.
  • This presents "Security features". However, it is incorrect and counter-productive to talk about security in terms of "features".

  Action item: this page should be entirely rewritten. Suggestions below.

• Authentication

  • The page should explain the purpose of authn and the scope of attacks/vulnerabilities that cockroahcDB intends to protect agaisnt. It does not.
  • The page mixes general concepts with practical "how to" examples, without distinguishing what is general and what is specific to the example. This incorrectly gives the impression that following the examples is sufficient to achieve good security.
  • The second sentence in the page suggests that only TLS authn is supported. This is completely and severely outdated.
  • The entire page only explains TLS certificates and is silent on the diversity of other authentication methods. It should list all the authn methods and explain what attack vectors they protect against.
  • The page should explain the HBA configuration mechanism.
  • The page does not adequately distinguish node-node, node-client RPC, node-client SQL and node-client HTTP authentication. There is a buried sentence that tries to make this distinction but it does not really succeeds. Instead that distinction should be front and foremost.

  Action item: page should be discarded and replaced by two different pages. Suggestions below.

• Encryption

  • The page should explain the purpose of encryption (not just what it does) by explaining the attack vectors and the scope of vulnerability that CockroahcDB aims to protect against. It does not currently.

  • The page should start by distinguishing the purpose of network encryption and encryption-at rest, and how they solve different problems: they help reduce different attack vectors. It does not currently.

  • The page groups backup encryption and data encryption-at-rest with the suggestion that they are related. In fact they are covering different attack models and either can be deployed independently from the other.

  Action items: introduce a proper overview section, then split the encryption features in different sub-pages.

• Authorization

  • The page should explain the purpose of authorization (not just what it does) by explaining the attack vectors and the scope of vulnerability that CockroahcDB aims to protect against. It does not currently. (That said, the first paragraph is a good introduction of what authz currently provides)

  • The page only explains SQL authorization. It should explain authorization of all the various services offered by CockroachDb including CLI admin commands, HTTP APIs, admin UI etc. It currently does not.

  • Regarding SQL authorization:

    • The page should not talk about root too much, as we are aiming to remove access to that user account from end-users. Currently root is prominently featured at the beginning the page.
    • The page is not yet up to date with the general concepts of "user" and "role", and how they overlap.
    • The page does not yet explain the CREATEROLE privilege.

  Action items: the intro of the page should be extended. The SQL authz explanations moved to a sub-page. Authz for the other services should be added side-by-side with SQL authz.

• SQL audit logging

  • The page should explain the purpose of audit logging (not just what it does) by explaining the attack vectors and the scope of vulnerability that CockroahcDB aims to protect against. It does not currently.
  • The page currently introduces the feature using a random use case (logging access to PII data), whereas the feature is intended to cover a much broader set of use cases. The current intro gives the impression that the feature is only suitable for that purpose.
  • This feature selection is quite random and the page title does not fit well at the same "level" as the other headings in the Security doc section.
  • The page does not emphasize/highlight the synchronous aspects of audit logging. It should.
  • The page does not explain that there are multiple audit logs, not just SQL queries. It should.
  • The page does not link to general security best practices wrt logging. It should.

  Action items: Introduce a new page on Logging and Non-repudiation. Explain the security objectives and how the DBA should work together with CockroachDB to achieve non-repudiation objectives. Provide a list of all the audit logs and how they are configured. Move the current SQL audit logging page into a sub-page of that.

• GSSAPI Authentication

  • This page is really a sub-section of "Authentication" and should not be at the top level like this.
  • The page should explain how GSSAPI differs from the other authn methods and what class of security vulnerabilities it protects again. It does not currently.
  • The page should explain how GSSAPI support in CockroachDB is different from that in PostgreSQL. It should explain that they are intendedly similar (HBA config, options etc) but the crdb feature coverage is limited.
  • It should explain that the support will be extended and that were are seeking input from users.
  • The page does not present general Kerberos concepts: what is a principal, what is a token, etc. It should, before presenting how-to guides with the two kerberos authn providers.

  Action items: Move this doc as sub-page of Authentication. Explain Kerberos concepts at the start.

Proposed structure

Let's aim for something like that:

• Overview
  • Security architecture
  • Scope of protections
• Security for DBAs
  • Logging and non-repudiation
    • Setting up and using audit logs
    • Setting up log collection into secure enclaves
    • Managing log rotation
  • Data encryption
    • Encryption at rest
    • Backup encryption
  • Network security
    • TLS best practices
    • Using network isolation for additional security
  • Server-side configuration of authn and authz
    • Setting up authn
      • Setting up TLS certs
      • Passwords and best practices
      • GSSAPI
      • Advanced: HBA configuration
    • Role delegation
• Security for application developers
  • SQL Authentication
    • Using TLS client certs
    • Using passwords
    • Using GSSAPI
  • SQL Authorization
    • Using roles
    • Using privileges
• Best practices
  • Personal development cluster
    • Prefer cockroach demo
    • Use crdb-generated certs with start-single-node
    • Avoid --insecure
  • Cloud applications
    • Integrate with AWS IAM to set up certs
    • Password management best practices, leveraging CREATELOGIN
    • Checklist: ensure node are not directly accessible from the public internet; restrict access to the SQL load balancer
    • Checklist: avoid --insecure
  • Enterprise security
    • How to use separate addresses/ports to set up a DMZ
    • Directory integration best practices
    • Checklist: ensure node are not directly accessible from the public internet; restrict access to the SQL load balancer
    • Checklist: avoid --insecure

Jira Issue: DOC-595

[Amruta-Ranade]

cc @thtruo