docs: improve readme, add security policy (#8)

joshuasing · Nov 5, 2024 · ce437a5 · ce437a5
1 parent 2f315b5
commit ce437a5
Show file tree

Hide file tree

Showing 2 changed files with 158 additions and 1 deletion.
diff --git a/README.md b/README.md
@@ -1,3 +1,107 @@
 # Starlink Prometheus Exporter
 
-A simple Starlink exporter for Prometheus. **Not affiliated with Starlink or SpaceX.**
+[![Go Reference](https://pkg.go.dev/badge/github.com/joshuasing/starlink_exporter.svg)](https://pkg.go.dev/github.com/joshuasing/starlink_exporter)
+[![Go Report Card](https://goreportcard.com/badge/github.com/joshuasing/starlink_exporter)](https://goreportcard.com/report/github.com/joshuasing/starlink_exporter)
+[![Go Build Status](https://github.com/joshuasing/starlink_exporter/actions/workflows/go.yml/badge.svg)](https://github.com/joshuasing/starlink_exporter/actions/workflows/go.yml)
+[![MIT License](https://img.shields.io/badge/license-MIT-2155cc)](LICENSE)
+
+A simple Starlink exporter for Prometheus. *Not affiliated with Starlink or SpaceX.*
+
+## Installation
+
+### Binaries
+
+Pre-built binaries are available from [GitHub Releases](https://github.com/joshuasing/starlink_exporter/releases).
+
+**Flags**
+
+```shell
+starlink_exporter --help
+# Usage of starlink_exporter:
+#   -dish string
+#         Dish address (default "192.168.100.1:9200")
+#   -listen string
+#         Listen address (default ":9451")
+```
+
+**Example**
+
+```shell
+starlink_exporter
+# 2024/11/05 12:03:48 INFO Starting Starlink exporter
+# 2024/11/05 12:03:48 INFO Connecting to Starlink Dishy address=192.168.100.1:9200
+# 2024/11/05 12:03:48 INFO HTTP server listening address=:9451
+```
+
+### Docker
+
+Docker images are published to both [GitHub Container Registry (ghcr.io)](https://ghcr.io/joshuasing/starlink_exporter)
+and [Docker Hub](https://hub.docker.com/r/joshuasing/starlink_exporter).
+
+```shell
+docker run -p 9451:9451 ghcr.io/joshuasing/starlink_exporter:latest
+# Status: Downloaded newer image for ghcr.io/joshuasing/starlink_exporter:latest
+# 2024/11/05 12:03:48 INFO Starting Starlink exporter
+# 2024/11/05 12:03:48 INFO Connecting to Starlink Dishy address=192.168.100.1:9200
+# 2024/11/05 12:03:48 INFO HTTP server listening address=:9451
+```
+
+### Prometheus
+
+To use the Starlink Prometheus Exporter, you need to configure Prometheus to scrape from the exporter:
+
+```yaml
+scrape_configs:
+  - job_name: "starlink"
+    scrape_interval: 3s # This can be whatever you would like.
+    static_configs:
+      - targets: [ "localhost:9451" ]
+```
+
+*Change `scrape_interval` and the address to match your setup.*
+
+## Contributing
+
+All contributions are welcome! If you have found something you think could be improved, or have discovered additional
+metrics you would like included, please feel free to participate by creating an issue or pull request!
+
+### Building
+
+Steps to build starlink_exporter.
+
+**Prerequisites**
+
+- Go v1.22 or newer (https://go.dev/dl/)
+
+**Build**
+
+- Make: `make` (`make deps lint-deps` if you are missing dependencies)
+- Standalone: `go build ./cmd/starlink_exporter/`
+
+### Contact
+
+This project is maintained by Joshua Sing. You see a list of ways to contact me on my
+website: https://joshuasing.dev/#contact
+
+#### Security vulnerabilities
+
+I take the security of my projects very seriously. As such, I strongly encourage responsible disclosure of security
+vulnerabilities.
+
+If you have discovered a security vulnerability in starlink_exporter, please report it in accordance with the
+project [Security Policy](SECURITY.md#reporting-a-vulnerability). **Never use GitHub issues to report a security
+vulnerability.**
+
+### License
+
+starlink_exporter is distributed under the terms of the MIT License.<br/>
+For more information, please refer to the [LICENSE](LICENSE) file.
+
+### Disclaimer
+
+This project is an independent, open-source Prometheus exporter and is not officially associated with, endorsed by, or
+in any way affiliated with SpaceX, Starlink, or any of their subsidiaries or affiliates. This project's purpose is to
+provide a tool for easily monitoring your Starlink Dishy with Prometheus, and is not authorised or supported by SpaceX
+or Starlink in any way.
+
+*SpaceX, Starlink, and any related logos or trademarks are the property of Space Exploration Technologies Corp.*
diff --git a/SECURITY.md b/SECURITY.md
@@ -0,0 +1,53 @@
+# Security Policy
+
+The purpose of this document is to outline how project maintainers will handle any discovered security vulnerabilities.
+
+## Supported Versions
+
+Security patches will be provided **only** for the latest release of `starlink_exporter`. This policy ensures that
+security updates are concentrated on the most up-to-date and stable version of the project. **Older versions will not
+receive security patches.**
+
+| Version   | Supported |
+|-----------|-----------|
+| `0.2.x`   | ✅         |
+| < `0.2.x` | ❌         |
+
+## Reporting a Vulnerability
+
+If you discover a security vulnerability in this project, we encourage you to report it to the project maintainer as
+soon as possible so that we can investigate and resolve the issue. I take security very seriously and will work quickly
+to address any confirmed vulnerabilities.
+
+You can report a security vulnerability by:
+
+- [Create a vulnerability report on GitHub](https://github.com/joshuasing/starlink_exporter/security/advisories/new)
+- Send an email to `security@joshuasing.dev` (if possible, encrypt the email using GPG -
+  see [here](https://joshuasing.dev/gpg/))
+
+I will acknowledge your report within 48 hours and aim to resolve critical issues within 30 days. In cases where the
+issue is particularly complex, the resolution may take longer, but I will keep you informed of progress. Your efforts
+to improve the security of this project are greatly appreciated.
+
+**Never disclose security vulnerabilities publicly, especially on GitHub issues.**
+
+## Responsible Disclosure and Credit
+
+I take the security of my projects and their users very seriously. As such, I encourage people to responsibly disclose
+security vulnerabilities. If you report a security vulnerability responsibly, it helps protect the project and its
+users, and you will also be credited when a Security Advisory is published.
+
+I define responsible disclosure as follows:
+
+- Disclosing the discovered vulnerability directly to the project maintainer.
+- Not sharing, publishing or disclosing information about the vulnerability prior to it being reported.
+- Allowing a reasonable period of time (typically up to 90 days) after reporting the vulnerability to investigate and
+  resolve the issue, before you publicly disclose information about the vulnerability or its existence.
+- Never attempting to exploit or take advantage of the vulnerability or any related vulnerabilities against any system
+  not owned by yourself.
+
+## Conclusion
+
+By following this Security Policy, I aim to improve and maintain the security of my projects.
+If you have any questions or concerns about this policy or this project's security practices, please do not hesitate to
+contact me (see https://joshuasing.dev/#contact).