security: validate key query param and fix /count return type (#231)

- server: validate the key query parameter against a strict charset (letters, digits, _ : -, max 64) so the API cannot be used to probe arbitrary redis keys; invalid keys return 400

- server: /count without a key returned a bare int which Flask rejects; always return a string

- README: document API_KEY and add a security note about exposing the pool publicly without authentication

Refs #228

Author: Germey

README.md

@@ -259,6 +259,9 @@ get random proxy 116.196.115.209:8080
 - API_HOST：代理 Server 运行 Host，默认 0.0.0.0
 - API_PORT：代理 Server 运行端口，默认 5555
 - API_THREADED：代理 Server 是否使用多线程，默认 true
+- API_KEY：API 访问鉴权密钥，默认空（即不鉴权）。设置后，调用 `/random`、`/all`、`/count` 需在请求头携带 `API-KEY`，详见下方「安全性」说明
+
+> ⚠️ 安全提示：代理 Server 默认监听 `0.0.0.0` 且 `API_KEY` 默认为空，任何能访问该端口的人都可以调用 `/random`、`/all`、`/count`。如果将代理池**暴露到公网**，请务必设置 `API_KEY`，并配合防火墙/安全组限制来源。`key` 查询参数已做格式校验，仅允许字母、数字及 `_ : -`，最长 64 位。
 
 ### 日志
 

proxypool/processors/server.py

@@ -1,5 +1,6 @@
 import hmac
-from flask import Flask, g, request
+import re
+from flask import Flask, g, request, abort
 from proxypool.exceptions import PoolEmptyException
 from proxypool.storages.redis import RedisClient
 from proxypool.setting import API_HOST, API_PORT, API_THREADED, API_KEY, IS_DEV, PROXY_RAND_KEY_DEGRADED
@@ -11,6 +12,10 @@
 if IS_DEV:
     app.debug = True
 
+# allowed characters for the `key` query parameter that selects a redis sub-pool;
+# restricts to a safe charset to avoid probing arbitrary redis keys via the API
+VALID_KEY_PATTERN = re.compile(r'^[a-zA-Z0-9_:\-]{1,64}$')
+
 
 def auth_required(func):
     @functools.wraps(func)
@@ -41,6 +46,18 @@ def get_conn():
     return g.redis
 
 
+def get_request_key():
+    """
+    read the `key` query parameter and validate its format;
+    reject unexpected characters to avoid redis key probing/injection
+    :return: validated key or None
+    """
+    key = request.args.get('key')
+    if key and not VALID_KEY_PATTERN.match(key):
+        abort(400, description='invalid key parameter')
+    return key
+
+
 @app.route('/')
 @auth_required
 def index():
@@ -59,7 +76,7 @@ def get_proxy():
     if PROXY_RAND_KEY_DEGRADED is set to True, will get a universal random proxy if no proxy found in the sub-pool
     :return: get a random proxy
     """
-    key = request.args.get('key')
+    key = get_request_key()
     conn = get_conn()
     # return conn.random(key).string() if key else conn.random().string()
     if key:
@@ -78,7 +95,7 @@ def get_proxy_all():
     get a random proxy
     :return: get a random proxy
     """
-    key = request.args.get('key')
+    key = get_request_key()
 
     conn = get_conn()
     proxies = conn.all(key) if key else conn.all()
@@ -98,8 +115,8 @@ def get_count():
     :return: count, int
     """
     conn = get_conn()
-    key = request.args.get('key')
-    return str(conn.count(key)) if key else conn.count()
+    key = get_request_key()
+    return str(conn.count(key)) if key else str(conn.count())
 
 
 if __name__ == '__main__':