docs: add a topic about security

doc/.wordlist.txt

@@ -4,6 +4,7 @@ APIs
 balancer
 Charmhub
 CLI
+Coverity
 dropdown
 Diátaxis
 EBS
@@ -36,4 +37,6 @@ subtree
 subfolders
 UI
 VM
+wifi
+Wireguard
 YAML

doc/explanation.md

@@ -20,6 +20,12 @@ Network configuration abstraction via `systemd-generator`
 Netplan Design <https://netplan.io/design>
 ```
 
+## Security
+
+```{toctree}
+security
+```
+
 ## FAQs
 
 Find answers to common questions

doc/security.md

@@ -0,0 +1,45 @@
+---
+title: "Netplan Security"
+---
+
+Overview of security aspects of Netplan.
+
+## Storing credentials
+
+Credentials, such as VPN keys and wifi passwords, are stored along with the rest
+of the configuration in YAML files. Netplan expects that all your YAML files
+will belong to the root user and only have permissions to be read by root (`chmod 600`).
+When storing credentials, you must be extra cautious and make sure your YAML files are not
+readable by unprivileged users.
+
+When using Network Manager to manage Wireguard tunnels, you can rely on an
+external key chain to store your private keys. For more details, check `private-key-flags`
+in the Netplan YAML configuration reference.
+
+Security advice: make sure all your YAML files in `/etc/netplan`, `/run/netplan` and
+`/lib/netplan` are not readable by non-privileged users.
+
+## Static analysis with Coverity
+
+To ensure that common issues will not sneak undetected in our code base,
+we scan it periodically with Coverity. Through Coverity static analysis we
+can achieve some degree of confidence that some types of issues, such as
+obvious memory leaks, will not stay unnoticed in the code.
+
+## Memory issue checks
+
+As part of our CI workflows, we build Netplan with GCC's address sanitiser and
+run unit tests and the Netplan generator against a number of YAML files. This helps
+us to detect issues, such as memory leaks and buffer overflows, at runtime using real
+configuration as input. When a memory issue is detected the process will crash, letting
+us know that some issue was introduced in the change.
+
+Every time a Pull Request is created or changes are merged to the main branch,
+these tests will be executed and, if a crash happens, the workflow will fail. 
+
+## Binary package hardening
+
+On Ubuntu and Debian, Netplan is built (and in fact most of the binary packages are)
+with a number of security flags that will apply some hardening to the resulting binary.
+That is intended to make the life of attackers harder in case any security issue is
+discovered. See `dpkg-buildflags(1)` for details.