ebolo/CaddyManager
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
c484014752f4e30a976396f48cdf5e5cd22ffe61
CaddyManager/README.md
T
eboloandClaude Opus 5 c484014752
Caddy Manager CI build / docker (push) Failing after 1m2s
Details
Harden the read path, forwarded headers and security docs 
Found while investigating an unrelated Gitea compromise: CaddyManager itself
was not involved, but reviewing it turned up three things worth closing.

Reading a configuration was the only file operation that did not validate the
name. Saving, renaming and deleting all reject `..`, `/` and `\`, so the read
path was the one way to leave the configuration directory and pull in any
`*.caddy` file on the host. The HTTP API happened to be covered, because GET
checks the name against the directory listing first, but the UI calls the
service directly and nothing stopped it.

Forwarded headers were trusted from any peer. That is correct only while the
container port is unreachable except through the proxy; the moment it is
published, a caller dictates the scheme, host and client address the app
believes in. Loopback and private space cover a proxy on a Docker network or on
the host, which is the documented deployment, and ignore everyone else.

The README never said that the `X-Api-Key` check guards `/api/*` and nothing
else, so the UI - which rewrites Caddyfiles and holds the Docker socket - reads
as protected when it is not. It now says so, and warns about the specific shape
that bit us: a second hostname added for machine callers whose only extra
directive is a `tls` line, which serves the unauthenticated UI to anyone who
can resolve it.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-09-12 17:05:52 +07:00

359 lines
14 KiB
Markdown
Raw Blame History

<!-- Improved compatibility of back to top link: See: https://github.com/othneildrew/Best-README-Template/pull/73 -->
<a id="readme-top"></a>
<!--
*** Thanks for checking out the Best-README-Template. If you have a suggestion
*** that would make this better, please fork the repo and create a pull request
*** or simply open an issue with the tag "enhancement".
*** Don't forget to give the project a star!
*** Thanks again! Now go create something AMAZING! :D
-->
<!-- PROJECT SHIELDS -->
<!--
*** I'm using markdown "reference style" links for readability.
*** Reference links are enclosed in brackets [ ] instead of parentheses ( ).
*** See the bottom of this document for the declaration of the reference variables
*** for contributors-url, forks-url, etc. This is an optional, concise syntax you may use.
*** https://www.markdownguide.org/basic-syntax/#reference-style-links
-->
<!-- PROJECT LOGO -->
<br />
<div align="center">
[//]: # ( <a href="https://github.com/othneildrew/Best-README-Template">)
[//]: # ( <img src="images/logo.png" alt="Logo" width="80" height="80">)
[//]: # ( </a>)
<h3 align="center">Caddy Manager</h3>
<p align="center">
A UI for managing Caddy configuration files
<br />
<a href="https://github.com/daothanhduy305/CaddyManager/blob/main/README.md"><strong>Explore the docs »</strong></a>
<br />
<br />
<a href="https://github.com/daothanhduy305/CaddyManager/issues/new">Report Bug (label bug)</a>
&middot;
<a href="https://github.com/daothanhduy305/CaddyManager/issues/new">Request Feature (label enhancement)</a>
[//]: # ( <a href="https://github.com/othneildrew/Best-README-Template">View Demo</a>)
[//]: # ( &middot;)
</p>
</div>
<!-- TABLE OF CONTENTS -->
<details>
<summary>Table of Contents</summary>
<ol>
<li>
<a href="#about-the-project">About The Project</a>
<ul>
<li><a href="#built-with">Built With</a></li>
</ul>
</li>
<li>
<a href="#getting-started">Getting Started</a>
<ul>
<li><a href="#prerequisites">Prerequisites</a></li>
<li><a href="#installation">Installation</a></li>
</ul>
</li>
<li><a href="#usage">Usage</a></li>
<li><a href="#roadmap">Roadmap</a></li>
<li><a href="#contributing">Contributing</a></li>
<li><a href="#license">License</a></li>
<li><a href="#contact">Contact</a></li>
<li><a href="#acknowledgments">Acknowledgments</a></li>
</ol>
</details>
<!-- ABOUT THE PROJECT -->
## About The Project
[//]: # ([![Product Name Screen Shot][product-screenshot]]&#40;https://example.com&#41;)
Caddy Management is an opinionated UI for managing Caddy configuration files. It is designed to be simple and easy to use. The architecture is based on the following principles:
- There has been a Caddy container running on the host machine
- The Caddy container is having its configuration files organized as:
- A Caddyfile contains the global configuration, and ending with the line `import *.caddy`
- Other proxy configurations are saved in individual `*.caddy` files
<p align="right">(<a href="#readme-top">back to top</a>)</p>
### Built With
[![DotNet][DotNet]][DotNet-url]
[![Gitea][Gitea]][Gitea-url]
[![Docker][Docker]][Docker-url]
* DotNet 9 with Blazor and [MudBlazor](https://mudblazor.com/)
* Source code and container registry are stored with Gitea
* Docker is used for containerization with DotNet container publishing
<p align="right">(<a href="#readme-top">back to top</a>)</p>
<!-- GETTING STARTED -->
## Getting Started
Given that there has already been a Caddy container running on the host machine, the following steps are required to set up the Caddy Manager using Docker compose.
### Prerequisites
These software are required to be installed on the host machine:
* Docker. Follow the instructions at [https://docs.docker.com/get-docker/](https://docs.docker.com/get-docker/)
* Caddy container. Follow the instructions at [https://caddyserver.com/docs/install](https://caddyserver.com/docs/install#docker)
* The Caddy container is having its configuration files organized at:
```yaml
volumes:
- /path/to/configs:/etc/caddy
```
### Global Caddy configuration
Add this directive at the end of your caddy configuration (global):
```
import *.caddy
```
This is to have the caddy files managed by this application be imported and work as expected.
### Installation with Docker compose
```yaml
services:
caddy:
image: caddy:latest
container_name: caddy
restart: always
network_mode: "host"
security_opt:
- label:disable
volumes:
- /root/compose/caddy/config:/etc/caddy
- /etc/localtime:/etc/localtime:ro
caddy-manager:
image: ghcr.io/daothanhduy305/caddymanager
container_name: caddy-manager
restart: always
environment:
ASPNETCORE_ENVIRONMENT: "Production"
CaddyService__ConfigDir: "/config"
DockerService__CaddyContainerName: "caddy"
# Path to the Caddyfile as seen from inside the caddy container. Must match the container side of the
# caddy container's config volume. Defaults to /etc/caddy/Caddyfile, so this line is optional above.
DockerService__CaddyConfigPathInContainer: "/etc/caddy/Caddyfile"
# Shared key for the HTTP API (see "HTTP API" below). Leave it out to keep the API closed.
Api__Key: "change-me"
# To have the access to the caddy config file
user: "1000:1000"
# The .NET GC sizes its heap against the cgroup limit, so this both caps the worst
# case and makes the runtime self-tune downward. Raise it if you run many configs.
mem_limit: 256m
memswap_limit: 256m
ports:
- "8080:8080"
volumes:
- /root/compose/caddy/config:/config
- /var/run/docker.sock:/var/run/docker.sock
```
<p align="right">(<a href="#readme-top">back to top</a>)</p>
<!-- USAGE EXAMPLES -->
## Usage
Currently, the Caddy Manager is able to:
- List all the Caddy configuration files
- Edit the content of the Caddy configuration files by clicking on the file name
- Create and manage the caddy files
- Edit the global Caddy configuration file by using the tab "Global Cadddyfile"
- Apply configuration changes with a graceful `caddy reload` (no dropped connections, and Caddy validates the
configuration first, so a broken file is reported back instead of taking the proxy down)
- Restart caddy container on demand
- Parse simple information from the caddy configurations
- Do all of the above over HTTP, for scripts and other services (see below)
### HTTP API
The same operations are exposed as a JSON API, documented with OpenAPI:
- Interactive documentation: `/scalar`
- OpenAPI document: `/openapi/v1.json`
Every request needs the shared key in the `X-Api-Key` header. The key comes from `Api:Key`
(environment variable `Api__Key`). **While no key is configured the API is disabled and every
endpoint answers `503`** — nothing is exposed by accident.
| Method | Endpoint | Description |
| --- | --- | --- |
| `GET` | `/api/configurations` | List the reverse proxy configurations |
| `GET` | `/api/configurations/{name}` | Get one configuration with its raw content |
| `POST` | `/api/configurations` | Create a configuration (`{ "fileName": "...", "content": "..." }`) |
| `PUT` | `/api/configurations/{name}` | Replace a configuration's content (`{ "content": "..." }`) |
| `POST` | `/api/configurations/{name}/rename` | Rename a configuration (`{ "newFileName": "..." }`) |
| `DELETE` | `/api/configurations/{name}` | Delete a configuration |
| `GET` | `/api/caddyfile` | Get the global Caddyfile |
| `PUT` | `/api/caddyfile` | Replace the global Caddyfile (`{ "content": "..." }`) |
| `POST` | `/api/caddy/reload` | Graceful `caddy reload` |
| `POST` | `/api/caddy/restart` | Restart the Caddy container |
`{name}` is the file name without the `.caddy` extension, as shown in the UI.
```shell
curl -H "X-Api-Key: change-me" http://localhost:8080/api/configurations
curl -X POST http://localhost:8080/api/configurations \
-H "X-Api-Key: change-me" -H "Content-Type: application/json" \
-d '{"fileName":"example","content":"example.com {\n\treverse_proxy 10.0.0.2:8080\n}"}'
curl -X POST -H "X-Api-Key: change-me" http://localhost:8080/api/caddy/reload
```
Renaming moves the file only; if the global Caddyfile imports the old name, update that import
yourself (the UI warns about this too).
> Note: the app redirects HTTP to HTTPS, so a direct `curl http://...` against the container port
> gets a `307`. Add `-L`, call it over HTTPS, or go through your reverse proxy.
### Security model
Read this before exposing the container port anywhere.
**The web UI has no authentication of its own.** The `X-Api-Key` check applies to `/api/*` only.
Everything else — the whole Blazor UI, which can rewrite any `*.caddy` file, replace the global
Caddyfile, and reload or restart Caddy — is served to whoever can open the port. The container also
mounts the Docker socket in order to reload Caddy, so control of the UI is control of the Docker
daemon on that host.
So: **put an authenticating reverse proxy in front of this app, and do not publish its port past
that proxy.** Any of the usual options works — the maintainer's own deployment uses
[Authentik](https://goauthentik.io/) forward auth:
```caddy
example.com {
route {
import authentik_forwardauth
reverse_proxy localhost:8080
}
}
```
Two things worth checking in your own setup:
- If you expose a second hostname for machine callers (so scripts can use `X-Api-Key` without going
through SSO), scope it to `/api/*` and refuse the rest, or that hostname serves the unauthenticated
UI as well. A hostname whose only extra directive is a `tls` line is **not** access control.
- `X-Forwarded-*` headers are honoured only from loopback and private address space (RFC 1918 /
RFC 4193). A proxy on a Docker network or on the host satisfies this; a proxy reaching the app from
a public address does not, and will see the app fall back to the real peer address and `http`.
<p align="right">(<a href="#readme-top">back to top</a>)</p>
<!-- ROADMAP -->
## Roadmap
- [x] Parse the caddy files to get more information, i.e. the domain names, the proxy addresses, etc.
See the [open issues](https://github.com/daothanhduy305/CaddyManager/issues) for a full list of proposed features (and known issues).
<p align="right">(<a href="#readme-top">back to top</a>)</p>
<!-- CONTRIBUTING -->
## Contributing
Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are **greatly appreciated**.
If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement".
Don't forget to give the project a star! Thanks again!
1. Fork the Project
2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`)
3. Commit your Changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the Branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request
<!-- LICENSE -->
## License
Distributed under the GNU GPLv3 License. See `COPYING` for more information.
<p align="right">(<a href="#readme-top">back to top</a>)</p>
<!-- CONTACT -->
## Contact
Ebolo - [@duydao](https://duydao.org) - daothanhduy305@gmail.com
Project Link: [CaddyManager](https://github.com/daothanhduy305/CaddyManager)
<p align="right">(<a href="#readme-top">back to top</a>)</p>
<!-- ACKNOWLEDGMENTS -->
## Acknowledgments
Use this space to list resources you find helpful and would like to give credit to. I've included a few of my favorites to kick things off!
* [Choose an Open Source License](https://choosealicense.com)
* [GitHub Emoji Cheat Sheet](https://www.webpagefx.com/tools/emoji-cheat-sheet)
* [Malven's Flexbox Cheatsheet](https://flexbox.malven.co/)
* [Malven's Grid Cheatsheet](https://grid.malven.co/)
* [Img Shields](https://shields.io)
* [GitHub Pages](https://pages.github.com)
* [Font Awesome](https://fontawesome.com)
* [React Icons](https://react-icons.github.io/react-icons/search)
<p align="right">(<a href="#readme-top">back to top</a>)</p>
<!-- MARKDOWN LINKS & IMAGES -->
<!-- https://www.markdownguide.org/basic-syntax/#reference-style-links -->
[contributors-shield]: https://img.shields.io/github/contributors/othneildrew/Best-README-Template.svg?style=for-the-badge
[contributors-url]: https://github.com/othneildrew/Best-README-Template/graphs/contributors
[forks-shield]: https://img.shields.io/github/forks/othneildrew/Best-README-Template.svg?style=for-the-badge
[forks-url]: https://github.com/othneildrew/Best-README-Template/network/members
[stars-shield]: https://img.shields.io/github/stars/othneildrew/Best-README-Template.svg?style=for-the-badge
[stars-url]: https://github.com/othneildrew/Best-README-Template/stargazers
[issues-shield]: https://img.shields.io/github/issues/othneildrew/Best-README-Template.svg?style=for-the-badge
[issues-url]: https://github.com/othneildrew/Best-README-Template/issues
[license-shield]: https://img.shields.io/github/license/othneildrew/Best-README-Template.svg?style=for-the-badge
[license-url]: https://github.com/othneildrew/Best-README-Template/blob/master/LICENSE.txt
[linkedin-shield]: https://img.shields.io/badge/-LinkedIn-black.svg?style=for-the-badge&logo=linkedin&colorB=555
[linkedin-url]: https://linkedin.com/in/othneildrew
[product-screenshot]: images/screenshot.png
[DotNet]: https://img.shields.io/badge/dotnet-563D7C?style=for-the-badge&logo=dotnet&logoColor=white
[DotNet-url]: https://dotnet.microsoft.com/en-us/
[Gitea]: https://img.shields.io/badge/Gitea-green?style=for-the-badge&logo=gitea&logoColor=white
[Gitea-url]: https://about.gitea.com/
[Docker]: https://img.shields.io/badge/Docker-blue?style=for-the-badge&logo=docker&logoColor=white
[Docker-url]: https://www.docker.com/
Reference in New Issue View Git Blame Copy Permalink