[3/4] incubator-brooklyn git commit: Docs: adds security-guidelines

[ha...@apache.org]

Docs: adds security-guidelines


Project: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/commit/4e0a82a0
Tree: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/tree/4e0a82a0
Diff: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/diff/4e0a82a0

Branch: refs/heads/master
Commit: 4e0a82a0086a6f2279311515b2fa03a49dbd3e5e
Parents: f87b2bf
Author: Aled Sage <al...@gmail.com>
Authored: Mon Nov 23 13:58:14 2015 +0000
Committer: Aled Sage <al...@gmail.com>
Committed: Tue Nov 24 15:08:50 2015 +0000

----------------------------------------------------------------------
 docs/guide/ops/index.md               |   1 +
 docs/guide/ops/security-guidelines.md | 102 +++++++++++++++++++++++++++++
 2 files changed, 103 insertions(+)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/4e0a82a0/docs/guide/ops/index.md
----------------------------------------------------------------------
diff --git a/docs/guide/ops/index.md b/docs/guide/ops/index.md
index bf40c1b..0123997 100644
--- a/docs/guide/ops/index.md
+++ b/docs/guide/ops/index.md
@@ -13,6 +13,7 @@ children:
 - externalized-configuration.md
 - requirements.md
 - production-installation.md
+- security-guidelines.md
 - troubleshooting/
 ---
 

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/4e0a82a0/docs/guide/ops/security-guidelines.md
----------------------------------------------------------------------
diff --git a/docs/guide/ops/security-guidelines.md b/docs/guide/ops/security-guidelines.md
new file mode 100644
index 0000000..d8c919d
--- /dev/null
+++ b/docs/guide/ops/security-guidelines.md
@@ -0,0 +1,102 @@
+---
+title: Security Guidelines
+layout: website-normal
+---
+
+## Brooklyn Server
+
+### Web-console and REST api
+
+Users are strongly encouraged to use HTTPS, rather than HTTP.
+
+The use of LDAP is encouraged, rather than basic auth.
+
+Configuration of "entitlements" is encouraged, to lock down access to the REST api for different 
+users.
+
+
+### Brooklyn user
+
+Users are strongly discouraged from running Brooklyn as root.
+
+For production use-cases (i.e. where Brooklyn will never deploy to "localhost"), the user under 
+which Brooklyn is running should not have `sudo` rights.
+
+
+### Persisted State
+
+Use of an object store is recommended (e.g. using S3 compliant or Swift API) - thus making
+use of the security features offered by the chosen object store.
+
+File-based persistence is also supported. Permissions of the files will automatically
+be 600 (i.e. read-write only by the owner). Care should be taken for permissions of the
+relevant mount points, disks and directories.
+
+
+## Credential Storage
+
+For credential storage, users are strongly encouraged to consider using the "externalised 
+configuration" feature. This allows credentials to be retrieved from a store managed by you, 
+rather than being stored within YAML blueprints or brooklyn.properties.
+
+A secure credential store is strongly recommended, such as use of 
+[HashiCorp's Vault](www.vaultproject.io) - see
+`org.apache.brooklyn.core.config.external.vault.VaultExternalConfigSupplier`.
+
+
+## Infrastructure Access
+
+### Cloud Credentials and Access
+
+Users are strongly encouraged to create separate cloud credentials for Brooklyn's API access.
+
+Users are also encouraged to (where possible) configure the cloud provider for only minimal API 
+access (e.g. using AWS IAM).
+
+<!--
+TODO: We should document the minimum requirements for AWS IAM required by Brooklyn
+-->
+
+
+### VM Image Credentials
+
+Users are strongly discouraged from using hard-coded passwords within VM images. Most cloud 
+providers/APIs provide a mechanism to instead set an auto-generated password or to create an 
+entry in `~/.ssh/authorized_keys` (prior to the VM being returned by the cloud provider).
+
+If a hard-coded credential is used, then Brooklyn can be configured with this "loginUser" and 
+"loginUser.password" (or "loginUser.privateKeyData"), and can change the password and disable 
+root login.
+
+
+### VM Users
+
+It is strongly discouraged to use the root user on VMs being created or managed by Brooklyn.
+
+
+### SSH keys
+
+Users are strongly encouraged to use SSH keys for VM access, rather than passwords.
+
+This SSH key could be a file on the Brooklyn server. However, a better solution is to use the 
+"externalised configuration" to return the "privateKeyData". This better supports upgrading of 
+credentials.
+
+
+## Install Artifact Downloads
+
+When Brooklyn executes scripts on remote VMs to install software, it often requires downloading 
+the install artifacts. For example, this could be from an RPM repository or to retrieve `.zip` 
+installers.
+
+By default, the RPM repositories will be whatever the VM image is configured with. For artifacts 
+to be downloaded directly, these often default to the public site (or mirror) for that software 
+product.
+
+Where users have a private RPM repository, it is strongly encouraged to ensure the VMs are 
+configured to point at this.
+
+For other artifacts, users should consider hosting these artifacts in their own web-server and 
+configuring Brooklyn to use this. See the documentation for 
+`org.apache.brooklyn.core.entity.drivers.downloads.DownloadProducerFromProperties`.
+