Add README

mothership · Sep 21, 2021 · c902f0c · c902f0c
1 parent 346f500
commit c902f0c
Show file tree

Hide file tree

Showing 6 changed files with 92 additions and 0 deletions.
diff --git a/README.md b/README.md
@@ -0,0 +1,50 @@
+# RDS Proxy
+
+A two-layer proxy for connecting into RDS postgres databases 
+based on IAM authentication. 
+
+This tool allows you to keep your databases firewalled off, 
+manage database access through IAM policies, and no developer 
+will ever have to share or type a password.
+
+As a side note, this pairs extremely well with a tool like [saml2aws](https://github.com/Versent/saml2aws)
+to ensure AWS/database access uses temporary credentials.
+
+
+## General Usage
+
+[docs](./docs/README.md)
+
+## Design 
+
+One proxy is run in your VPC subnet that can reach your RDS instances,
+the other on your client machine (dev laptop, etc.) with access to 
+aws credentials.
+
+The client proxy is responsible for picking a host (RDS instance), and 
+generating a temporary password based on the local IAM identity. The
+client proxy injects the host and password into the postgres startup 
+message as additional parameters. 
+
+![Client startup flow](./docs/images/rds-proxy-client-startup-flow.png)
+
+The server proxy accepts a connection from the client proxy, and 
+unpacks the host and password parameters. It then opens a connection 
+to the RDS database and intercepts the authentication request. It then 
+passes along the password it received from the client, and forwards the 
+result to the client.
+
+![Auth overview](./docs/images/rds-proxy-auth-flow.png)
+
+## Security
+
+The security of this setup depends on the following assumptions:
+
+* Users do not share laptops / leave them unlocked.
+* No untrusted process on the client machine, or server can read the 
+  memory of the proxy process.
+* You have a secure tunnel, or other means of encrypting the connection to 
+  to the server-side proxy (VPN, SSH tunnel, k8s port-forward, etc.).
+* You have adequate IAM policies, restricting which the 
+  roles/databases a developer may use.
+
diff --git a/docs/.nojekyll b/docs/.nojekyll
diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,17 @@
+# RDS Proxy
+
+## General Usage
+
+For contributing, see [contribution guide](https://github.com/mothership/rds-auth-proxy).
+
+## Security
+
+The security of this setup depends on the following assumptions:
+
+* Users do not share laptops / leave them unlocked.
+* No untrusted process on the client machine, or server can read the 
+  memory of the proxy process.
+* You have a secure tunnel, or other means of encrypting the connection to 
+  to the server-side proxy (VPN, SSH tunnel, k8s port-forward, etc.).
+* You have adequate IAM policies, restricting which the 
+  roles/databases a developer may use.
diff --git a/docs/images/rds-proxy-auth-flow.png b/docs/images/rds-proxy-auth-flow.png
diff --git a/docs/images/rds-proxy-client-startup-flow.png b/docs/images/rds-proxy-client-startup-flow.png
diff --git a/docs/index.html b/docs/index.html
@@ -0,0 +1,25 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <title>RDS Proxy</title>
+  <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
+  <meta name="description" content="Description">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0, minimum-scale=1.0">
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/docsify-themeable@0/dist/css/theme-simple-dark.css">
+
+</head>
+<body>
+  <div id="app"></div>
+  <script>
+    window.$docsify = {
+      name: 'RDS Proxy',
+      repo: 'https://github.com/mothership/rds-auth-proxy',
+      loadSidebar: false,
+    }
+  </script>
+  <!-- Docsify v4 -->
+  <script src="//cdn.jsdelivr.net/npm/docsify@4"></script>
+  <script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-go.min.js"></script>
+</body>
+</html>