github.com/google/go-safeweb@v0.0.0-20231219055052-64d8cfc90fbb/README.md (about)

     1  # go-safeweb
     2  
     3  **DISCLAIMER**: This is not an officially supported Google product.
     4  
     5  `go-safeweb` is a collection of libraries for writing secure-by-default HTTP
     6  servers in Go.
     7  
     8  ## Contributing
     9  
    10  This project is in an early stage. We are currently **not accepting** any
    11  contributions.
    12  
    13  ## Overview
    14  
    15  The flexibility of Go’s [`net/http`](https://pkg.go.dev/net/http/) package
    16  allows users to quickly implement HTTP servers.
    17  
    18  Responses are then written simply as slices of bytes, headers can be arbitrarily
    19  manipulated and so on. This approach offers much needed flexibility for these
    20  who really need it.
    21  
    22  Unfortunately, this approach leaves great space for introducing security
    23  vulnerabilities and even experienced developers tend to do so.
    24  
    25  This document aims to design an HTTP API that eliminates whole classes of bugs,
    26  like Cross-Site Scripting (XSS) or Cross-Site Request Forgery (XSRF). This can
    27  be achieved by an approach known at Google as _safe coding_. Learn more at
    28  [Securing the Tangled Web (Chistoph Kern, 2014)](http://static.googleusercontent.com/media/research.google.com/en//pubs/archive/42934.pdf)
    29  or
    30  [Preventing Security Bugs through Software Design (Christoph Kern, 2016)](https://www.youtube.com/watch?v=ccfEu-Jj0as).
    31  
    32  ## Goals and Non-Goals
    33  
    34  ### Goals
    35  
    36  #### G1: Secure-by-default
    37  
    38  Security mechanisms are applied by default (opt-out, not opt-in).
    39  
    40  #### G2: Unsafe Usage is Easy to Review, Track and Restrict
    41  
    42  All opt-outs from security mechanisms are explicit. Wherever possible, they’re
    43  contained inside a package or an option that’s easy to restrict.
    44  
    45  #### G3: Designed for Evolving Security Requirements
    46  
    47  Enforcing new security measures is feasible through AST manipulation. Existing
    48  users can be migrated using static analysis and/or runtime monitoring. Read more
    49  [here](#evolving-security-requirements-example).
    50  
    51  #### G4: High Compatibility with Go’s Standard Library and Existing Open-Source Frameworks
    52  
    53  Whenever possible, keep existing layouts, function signatures and other API
    54  parts the same as the Go’s standard library. High compatibility enables wide
    55  adoption.
    56  
    57  ### Non Goals
    58  
    59  #### NG1: Safe API [Completeness](<https://en.wikipedia.org/wiki/Completeness_(logic)>)
    60  
    61  Creating safe APIs for all the corner cases might result in a bloated codebase.
    62  Our experience shows that this isn’t necessary.
    63  
    64  #### NG2: Full Compatibility with Go’s Standard Library and Existing Open-Source Frameworks
    65  
    66  Existing open-source frameworks or the Go standard library need to support each
    67  developer scenario. This would have left us with limited options of creating
    68  safe-by-default HTTP servers.
    69  
    70  #### NG3: Features That Are Not Security Critical
    71  
    72  Go Safe Web aims to help you create a secure-by-default Go HTTP server and
    73  nothing more. Features that are not security critical will not be added.
    74  Focusing solely on security allows us to maintain high compatibility with the
    75  standard library and makes adoption easier.
    76  
    77  ## Security Vulnerabilities and Mitigations
    78  
    79  On a high level, we plan to address, or provide the needed infrastructure to
    80  address, following issues (not an exhaustive list):
    81  
    82  - **XSS (cross-site scripting) and XSSI (cross-site script inclusion)** - e.g.
    83    by controlling how responses are generated
    84  - **XSRF (cross-site request forgery)** - e.g. by using Fetch Metadata policies,
    85    supporting token-based XSRF protection
    86  - **CORS (cross-origin resource sharing)** - e.g. by taking control of CORS
    87    response headers and handling CORS preflight requests
    88  - [**CSP (content security policy)**](https://csp.withgoogle.com/docs/index.html) -
    89    e.g. by automatically adding script nonces to HTML responses, adding relevant
    90    security headers
    91  - **Transport Security** - e.g. by
    92    [enforcing HSTS support](safehttp/plugins/hsts)
    93  - **IFraming** - e.g. by setting relevant HTTP headers to restrict framing or
    94    providing server-side support for origin selection
    95  - **Auth (access control)** - e.g. by providing infrastructure for plugging in
    96    access control logic in an uniform, auditable way
    97  - **HTTP Request Parsing Bugs** - e.g. by implementing strict and well
    98    documented parsing behavior
    99  - **Error responses** - e.g. by providing infrastructure for uniform error
   100    handling (e.g. to prevent accidental leaks or XSS from error responses)
   101  - **Enforcement of other security specific HTTP headers** -
   102    [here](safehttp/plugins/staticheaders)
   103  
   104  ## Appendix
   105  
   106  ### Evolving Security Requirements (example)
   107  
   108  Imagine an API for configuring access control. It features three types of rules:
   109  
   110  - `ALLOW(user)` - allows a given `user`
   111  - `DENY(user)` - denies a given `user` (has priority over `ALLOW`)
   112  - `REPORT(user)` - reports that it has seen a request from a given `user`
   113  
   114  Imagine now that at some point, security standards need to be increased and
   115  `user = "frombulator"` has been determined to not meet the desired bar.
   116  
   117  How do we, for all the services running in our company, address this?
   118  
   119  1.  For existing services, we add a `LegacyFrombulatorAccess` option like so:
   120      `security.AccessControl(rules, unsafe.LegacyFrombulatorAccess())`.
   121  1.  We change the `security.AccessControl()` call to add by default a
   122      `DENY("frombulator")` rule. This rule **is not added** if
   123      `unsafe.LegacyFrombulatorAccess` is applied.
   124  1.  Instead, `unsafe.LegacyFrombulatorAccess` adds a `REPORT("frombulator")`
   125      rule.
   126  
   127  This way, we have:
   128  
   129  - Ensured that all new callers of `security.AccessControl` use the safe setting
   130    by default.
   131  - Can monitor existing services dependence on calls from the `frombulator`.
   132    After a period of observation (let’s say, 30 days):
   133    - If the service doesn’t receive requests from the `frombulator`: **prune the
   134      `unsafe.LegacyFrombulatorAccess`** option.
   135    - If the service does receive requests from the `frombulator`: **inform the
   136      service owners and plan a fix.**
   137  
   138  Crucially, only the last case (dependence on unsafe configuration) requires
   139  engineering work per service. The rest can be automated.
   140  
   141  **This approach is possible due to careful API design.** A missing `DENY` or
   142  `REPORT` rule, or a single sink in the form of `security.AccessControl` would
   143  make this infeasible.
   144  
   145  ### Source Code Headers
   146  
   147  Every file containing source code must include copyright and license
   148  information. This includes any JS/CSS files that you might be serving out to
   149  browsers. (This is to help well-intentioned people avoid accidental copying that
   150  doesn't comply with the license.)
   151  
   152  Apache header:
   153  
   154      Copyright 2020 Google LLC
   155  
   156      Licensed under the Apache License, Version 2.0 (the "License");
   157      you may not use this file except in compliance with the License.
   158      You may obtain a copy of the License at
   159  
   160          https://www.apache.org/licenses/LICENSE-2.0
   161  
   162      Unless required by applicable law or agreed to in writing, software
   163      distributed under the License is distributed on an "AS IS" BASIS,
   164      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   165      See the License for the specific language governing permissions and
   166      limitations under the License.