Guard - an elegant IPQS plugin

Showcase
1

GitHub License GitHub Repo stars GitHub go.mod Go version
Static Badge

Intro

— Guard is an elegant IPQS plugin for Caddy. Acting as a middleware between your web server.

— Features are built in, you can tell Guard to intercept or to pass data to your web server.

Install

xcaddy build --with github.com/z3ntl3/caddyguard

Example

{
	order guard before reverse_proxy
}

:2000 {
	guard /api* {
		rotating_proxy 1.1.1.1 
		timeout 3s 
		ip_headers cf-connecting-ip {
			more1
			more2
			more3
		}
		pass_thru 
	}

	reverse_proxy  http://localhost:2000
}

Keep in mind that you need to order manually.

Caddyfile syntax

guard [matcher] {
    rotating_proxy <arg>
    timeout <arg>
    ip_headers <args...> {
        <arg> 
        <arg>
        <arg>
        ...
    }
    pass_thru 
}

Sub-directives

  • rotating_proxy <arg>

    Doc

    • Should comfort net.http.

    • Supported protocols are socks, http and https.

    • If scheme is not provided, http is assumed.

    Examples

     guard /api* {
    rotating_proxy 1.1.1.1    
 }

    Here http://1.1.1.1 is assumed.


     guard /api* {
    rotating_proxy socks5://1.1.1.1    
 }

    Here socks5://1.1.1.1 is assumed.

    NOTE

    Underlying client may change. Proxifier > may be binded to this plugin. Which is our own low-level proxy client library.

  • timeout <arg>

    Doc

    • Should comfort time.

    Aka arg values like: 10s, 1m etc…

    Examples

     guard /api* {
    timeout 1s    
 }

  • ip_headers <args...> {...}

    Doc

    • Can be arbitrary values. Tells Guard plugin to find the real ip address in one of those headers.

    Values like: cf-connecting-ip, x-forwarded-for and etc…, seem logical

    Examples

     guard /api* {
    ip_headers header1 {
         header2
    }
 }

  • pass_thru

    Doc


    Accepts no args, and disallows opening a block. It acts like a turn on.

    Providing pass_thru simply means to pass data down to the next handler, aka your web server/reverse proxy instead of writing a HTTP response itself. Provides useful data by manipulating the request headers, while it moves down to the next handlers.

    If pass_thru is provided, then there are some important headers your web server should consume:

    X-Guard-* Headers

    • X-Guard-Success

      If it is set to 1, it means success otherwise -1 means false.

    • X-Guard-Info

      Contains explainatory description.

    • X-Guard-Query

      The IP which got queried. Not present when X-Guard-Rate is UNKNOWN.

    • X-Guard-Rate

      Either DANGER | LEGIT | UNKNOWN

      DANGER

      Reports that the IP reputation is bad

      LEGIT

      Reports that the IP reputation is good

      LEGIT

      Reports that the IP reputation is unknown, aka scan failure. Typically exceeded timeout constraints.

Additional notes

Guard uses InternetDB to perform scans. It’s completely free, and allows high traffic throughput. You can always use rotating_proxy sub-directive with Guard to send rotated requests, to prevent rate limits if you require higher quota.

Determination of a bad IP happens in the following way:

  • If InternetDB knows anything about the queried IP, then it is an IP with bad reputation.

Credits

— Programmed by z3ntl3, will be used at the revamped api.pix4.dev.

1 Like
2

Very cool, thank you for sharing!!

2 Likes
3

FYI since v2.8.0 you can register a default directive order so that users don’t need to specify it in their config. It must be relative to another built-in Caddyfile directive.

3 Likes