colin
/
ntfy
1
0
Fork 0
Code Pull Requests Packages Activity

Update README.md

This commit is contained in:
colin 2024-01-21 20:53:13 +00:00
parent efa0b2f9dd
commit 66b0b358eb
1 changed files with 67 additions and 73 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

140
README.md
View File

@ -1,43 +1,75 @@
<!-- # build:0 --> <!-- # build:0 -->
# Known Weaknesses and Caveats
While this Trivy container is built with reliability in mind, it's important to note that it primarily focuses on scanning and reporting. There isn't an advanced validation mechanism beyond ensuring that the container builds and runs the scans correctly. Future improvements include more robust testing and validation measures.
## ToDo ## ToDo
* [ ] Implement more comprehensive testing beyond basic functionality. * [ ] Develop a more robust integration system for complex network setups. [Not planned]
* [ ] Integrate safe testing with known vulnerable files for end-to-end testing. * [ ] Enhance logging and monitoring capabilities for better observability. []
* [ ] Develop a consistent reporting system for scan results. * [ ] Explore security enhancements and vulnerability checks.
* [ ] Experiment with and test quarantine measures for identified vulnerabilities.
## Disclaimer ## Disclaimer
Understanding the scope and limitations of a vulnerability scanner like Trivy is crucial. A Trivy scan aims to increase observability and enable actions on detectable vulnerabilities, not guarantee future system security. Positive detections should prompt IT staff to consider appropriate remediation steps. Headscale, as a self-hosted control server, does not inherently solve all network security challenges. It's intended to simplify the management of Tailscale nodes within a private network. Network administrators should still apply best practices for security and monitor their network's activity.
## Considerations ## Considerations
Trivy, running as a Docker container, offers a certain level of security and obscurity. Its cryptographic signature and isolation from typical user space make it a less likely target for tampering by advanced attackers. While it includes a mode for potential quarantine actions, this feature is more theoretical. It has yet to be extensively tested in its current form. Users should exercise caution and use scan logs as a guide for manual file handling if necessary. Running Headscale as a Docker container provides certain advantages, such as ease of deployment and isolation. However, as with any network component, it should be deployed carefully within the context of your network's security architecture.
# Usage # Usage
Create a directory for the Trivy container configuration: First, create a directory for the Headscale container configuration:
```bash
mkdir -p ./headscale/
``` ```
mkdir -p /root/trivy/
``` Then, edit the Docker Compose file:
Then edit the Docker Compose file:
``` ```bash
nano /root/trivy/docker-compose.yml nano ./headscale/docker-compose.yml
``` ```
## Environment Variables and Defaults ## Environment Variables and Defaults
| Variable | Description | Default Value | | Variable | Description | Default Value |
|----------------|----------------------------------------------|------------------------| |-------------------------|----------------------------------------|---------------------------------|
| `TIMEOUT` | Maximum duration for a scan | `120m` | | `SERVER_URL` | URL that clients will connect to | `http://127.0.0.1:8080` |
| `SCANNERS` | Scanners to be used | `vuln,misconfig,secret`| | `LISTEN_ADDR` | Address for the server to listen on | `127.0.0.1:8080` |
| `IGNORE_UNFIXED`| Whether to ignore vulnerabilities without fixes | `false` | | `METRICS_LISTEN_ADDR` | Address for listening to metrics | `127.0.0.1:9090` |
| `LOW_PRIORITY` | Run scans with low CPU priority (nice 19) | `true` | | `GRPC_LISTEN_ADDR` | Address for listening for gRPC | `127.0.0.1:50443` |
| `DB_TYPE` | Type of database to use | `sqlite3` |
| `DB_PATH` | Path to the database file | `/var/lib/headscale/db.sqlite` |
#### Extended Variables and Defaults
| Variable Name | Description | Example Value |
| ------------------------------ | ---------------------------------------------------- | --------------------------------------- |
| `SERVER_URL` | The URL that clients will connect to | `http://127.0.0.1:8080` |
| `LISTEN_ADDR` | Address for the server to listen on | `127.0.0.1:8080` |
| `METRICS_LISTEN_ADDR` | Address for listening to metrics | `127.0.0.1:9090` |
| `GRPC_LISTEN_ADDR` | Address for listening for gRPC | `127.0.0.1:50443` |
| `GRPC_ALLOW_INSECURE` | Allow gRPC to run in INSECURE mode | `false` |
| `NOISE_PRIVATE_KEY_PATH` | Path to the Noise private key | `/var/lib/headscale/noise_private.key` |
| `IP_PREFIXES` | List of IP prefixes to allocate tailaddresses from | `["fd7a:115c:a1e0::/48", "100.64.0.0/10"]` |
| `DERP_ENABLED` | Whether to enable DERP server | `false` |
| `DERP_REGION_ID` | Region ID for the DERP server | `999` |
| `DERP_STUN_LISTEN_ADDR` | Address for the DERP STUN server to listen on | `0.0.0.0:3478` |
| `DERP_PRIVATE_KEY_PATH` | Path to the DERP server private key | `/var/lib/headscale/derp_server_private.key` |
| `ACME_URL` | URL to ACME directory for Let's Encrypt | `https://acme-v02.api.letsencrypt.org/directory` |
| `ACME_EMAIL` | Email to register with ACME provider | `example@email.com` |
| `TLS_LETSENCRYPT_HOSTNAME` | Domain name for TLS certificate | `mydomain.com` |
| `TLS_LETSENCRYPT_CACHE_DIR` | Path to store certificates and metadata for Let's Encrypt | `/var/lib/headscale/cache` |
| `DB_TYPE` | Database type (e.g., sqlite3, postgres) | `sqlite3` |
| `DB_PATH` | Path to the database file (for sqlite3) | `/var/lib/headscale/db.sqlite` |
To use these variables in your `config-example.yaml`, you would format them like this:
```yaml
server_url: ${SERVER_URL}
listen_addr: ${LISTEN_ADDR}
metrics_listen_addr: ${METRICS_LISTEN_ADDR}
...
```
### Note: ### Note:
By default, the container assumes a low-priority mode for scanning if the `LOW_PRIORITY` environment variable is not explicitly set. These variables can be customized to fit your network setup. Ensure that they align with your network's configuration and security policies.
## docker-compose.yml ## docker-compose.yml
@ -45,59 +77,21 @@ By default, the container assumes a low-priority mode for scanning if the `LOW_P
version: '3.8' version: '3.8'
services: services:
trivy: headscale:
image: git.nixc.us/colin/trivy:production image: headscale/headscale:latest
volumes: volumes:
- /:/mnt:ro - ./headscale/config:/etc/headscaled
- ./log:/log environment:
# Uncomment and modify the following lines to customize environment variables - SERVER_URL=${SERVER_URL}
# environment: - LISTEN_ADDR=${LISTEN_ADDR}
# TIMEOUT: "120m" # Default scan timeout - METRICS_LISTEN_ADDR=${METRICS_LISTEN_ADDR}
# SCANNERS: "vuln,misconfig,secret" # Scanners to be used - GRPC_LISTEN_ADDR=${GRPC_LISTEN_ADDR}
# IGNORE_UNFIXED: "false" # Whether to ignore unfixed vulnerabilities - DB_TYPE=${DB_TYPE}
# LOW_PRIORITY: "true" # Run scans with low CPU priority - DB_PATH=${DB_PATH}
read_only: true
tmpfs:
- /tmp
deploy:
resources:
limits:
cpus: '0.50' # Limit to 50% of a CPU
memory: 512M # Limit to 512 megabytes
```
Schedule regular scans using crontab:
```
crontab -e
```
Then add one of the following cron examples.
### Once a Week
To run the job every Sunday at midnight:
```cron
0 0 * * 0 /usr/bin/docker compose -f /root/trivy/docker-compose.yml up -d --pull --force-recreate trivy
```
### Once Every Two Weeks
For a bi-weekly schedule, specify two days of the month, like the 1st and 15th:
```cron
0 0 1,15 * * /usr/bin/docker compose -f /root/trivy/docker-compose.yml up -d --pull --force-recreate trivy
```
### Once a Month
To run the job on the first day of every month at midnight:
```cron
0 0 1 * * /usr/bin/docker compose -f /root/trivy/docker-compose.yml up -d --pull --force-recreate trivy
``` ```
### Notes: ### Notes:
- Verify that `/usr/bin/docker` is the correct path to your Docker binary. This path might vary. - Customize the environment variables in the `docker-compose.yml` file as needed.
- Replace `/root/trivy` with the directory path where your `docker-compose.yml` file is located. - You may need to adjust port mappings based on your specific network setup.
- The cron jobs will update the `trivy` container according to the specified schedule. Ensure this aligns with your maintenance and update policies. - Ensure that the Headscale container's configuration aligns with your security policies and network architecture.