starred/headscale
1
0
Fork 0
mirror of https://github.com/juanfont/headscale.git synced 2026-01-12 04:10:32 +01:00
Code Issues 98 Packages Projects Releases 10 Wiki Activity

fail2ban rule for API? #540

New Issue
Closed
opened 2025-12-29 02:19:40 +01:00 by adam · 4 comments
adam commented 2025-12-29 02:19:40 +01:00
Owner
Copy Link

Originally created by @unusualevent on GitHub (Aug 6, 2023).

Why

If headscale is part of the outer services of a network (along with email servers), it'd be great to have strong tooling to monitor and block attempts to authenticate to it, to disallow bruteforcing.

This is important for things like the API, but less well defined for things like wireguard itself, which doesn't provide good logging for key attempts for use in blocking. At least the other negotiation ports on headscale would be more secured.

Description

It would be nice to have a recommended filter & block action for headscale, to be used in fail2ban.

these can simply be documented in a section entitled "hardening".

For example:

you would need:

  1. a consistent location for authorization failures in logs
  2. a consistent regular expression for failures (to make a filter)
  3. a good action for failures (in mailu since it's containers it's slightly different) - to make the jail file
  4. a good spot in the documentation to place it
  5. a network to test the fail2ban rules with
Originally created by @unusualevent on GitHub (Aug 6, 2023). ## Why If headscale is part of the outer services of a network (along with email servers), it'd be great to have strong tooling to monitor and block attempts to authenticate to it, to disallow bruteforcing. This is important for things like the API, but less well defined for things like wireguard itself, which doesn't provide good logging for key attempts for use in blocking. At least the other negotiation ports on headscale would be more secured. ## Description It would be nice to have a recommended filter & block action for headscale, to be used in fail2ban. these can simply be documented in a section entitled "hardening". For example: - Vaultwarden's fail2ban documentation: https://github.com/dani-garcia/vaultwarden/wiki/Fail2Ban-Setup - Mailu's fail2ban documentation: https://mailu.io/1.9/faq.html#do-you-support-fail2ban you would need: 1. a consistent location for authorization failures in logs 2. a consistent regular expression for failures (to make a filter) 3. a good action for failures (in mailu since it's containers it's slightly different) - to make the jail file 4. a good spot in the documentation to place it 5. a network to test the fail2ban rules with
adam added the enhancement label 2025-12-29 02:19:40 +01:00
adam closed this issue 2025-12-29 02:19:40 +01:00
adam commented 2025-12-29 02:19:41 +01:00
Author
Owner
Copy Link

@juanfont commented on GitHub (Aug 27, 2023):

This can be implemented in a reverse proxy if needed.

@juanfont commented on GitHub (Aug 27, 2023): This can be implemented in a reverse proxy if needed.
adam commented 2025-12-29 02:19:41 +01:00
Author
Owner
Copy Link

@mathmaniac43 commented on GitHub (Jan 18, 2024):

Hello!

I am interested in hardening my Headscale instance as well. I am hosting it behind a Traefik reverse proxy, so I believe I could set up fail2ban or something like that in Traefik, which is great.

However, I am not sure HOW to do that, or specifically how to have Headscale pass along failures to authenticate to the reverse proxy to eventually decide to fail/block. Any guidance or ideas would be appreciated.

Thanks!

@mathmaniac43 commented on GitHub (Jan 18, 2024): Hello! I am interested in hardening my Headscale instance as well. I am hosting it behind a Traefik reverse proxy, so I believe I could set up fail2ban or something like that in Traefik, which is great. However, I am not sure HOW to do that, or specifically how to have Headscale pass along failures to authenticate to the reverse proxy to eventually decide to fail/block. Any guidance or ideas would be appreciated. Thanks!
adam commented 2025-12-29 02:19:42 +01:00
Author
Owner
Copy Link

@phs78 commented on GitHub (Jul 19, 2025):

  1. configure traefik to create an access log readable by fail2ban
  2. create a fail2ban filter that catches failregex = ^ - - [.] "GET /api/v1/apikey." 500 .*
  3. create a jail

I have this working. I just need to write it up and I'll share.

@phs78 commented on GitHub (Jul 19, 2025): 1. configure traefik to create an access log readable by fail2ban 2. create a fail2ban filter that catches failregex = ^<HOST> - - \[.*\] "GET /api/v1/apikey.*" 500 .* 3. create a jail I have this working. I just need to write it up and I'll share.
adam commented 2025-12-29 02:19:42 +01:00
Author
Owner
Copy Link

@numericOverflow commented on GitHub (Dec 28, 2025):

  1. configure traefik to create an access log readable by fail2ban

    1. create a fail2ban filter that catches failregex = ^ - - [.] "GET /api/v1/apikey." 500 .*

    2. create a jail

I have this working. I just need to write it up and I'll share.

@phs78 - you ever get around to sharing? Thought it'd be smart to get headscale hooked up to fail2ban if possible, since I see a ton of IPs that constantly try to connect to my setup.

@numericOverflow commented on GitHub (Dec 28, 2025): > 1. configure traefik to create an access log readable by fail2ban > > 2. create a fail2ban filter that catches failregex = ^ - - [._] "GET /api/v1/apikey._" 500 .* > > 3. create a jail > > > I have this working. I just need to write it up and I'll share. @phs78 - you ever get around to sharing? Thought it'd be smart to get headscale hooked up to fail2ban if possible, since I see a ton of IPs that constantly try to connect to my setup.
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
CLI
DERP
DNS
Nix
OIDC
SSH
bug
database
documentation
duplicate
enhancement
faq
good first issue
grants
help wanted
might-come
needs design doc
needs investigation
no-stale-bot
out of scope
performance
policy 📝
pull-request
Mirrored from GitHub Pull Request
 question
regression
routes
stale
tags
tailscale-feature-gap
well described ❤️
wontfix
No Label enhancement
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
adam
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: starred/headscale#540
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?