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 pass data all the way down 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

    UNKNOWN
    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 increase that when needed.

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.