Controller for PoW-Shield that calculates and assigns the optimal difficulty via request and waf trigger distributions based on machine learning model.
User interface for PoW-Phalanx can be found at PoW-Phalanx Controller UI
Todos:
- Socket connectivity with PoW Shield
- Statistics synchronization
- Difficulty control
- Model interaction interface
- Feature synchronization
- Ban state synchronization
- Controller graphics interface
- Security model update
- Unit test
Docker ^19.0.0 Nodejs ^14.0.0
- nodejs: .env (example: .env.example)
- docker-compose: docker-compose.yaml (example: docker-compose.example.yaml)
- docker run: -e parameter
| Variable | Default | Description |
|---|---|---|
| PORT | 6000 | port for phalanx instance |
| DATABASE_HOST | 127.0.0.1 | host for redis database |
| DATABASE_PORT | 6379 | port for redis database |
| DATABASE_PASSWORD | password for redis database | |
| SUBSCRIPTION_TOKEN | test-subscription-token | token for access to subscription endpoint |
| CONTROLLER_TOKEN | test-controller-token | token for access to controller endpoint |
| MODEL_TOKEN | test-model-token | token for access to model endpoint |
| CONTROLLER_BROADCAST_INTERVAL | 20 | interval(seconds) for phalanx to broadcast controller stats |
| STAT_FETCH_INTERVAL | 10 | interval(seconds) for phalanx to broadcast fetch directive to subscibed pow-shield instances |
| STAT_KEEP_HISTORY_TIME | 3600 | length(seconds) for phalanx to keep history fetched from pow-shield instances |
| RESOURCE_MONITOR | off | connect to resource monitor on backend |
| RESOURCE_MONITOR_HOST | resource monitor host | |
| RESOURCE_MONITOR_PORT | resource monitor port | |
| SETTINGS_FETCH | off | fetch settings dump alongside batch stats |
| RESTFUL | on | enable restful api |
| RESTFUL_PORT | 9000 | port for restful api |
# Clone repository
git clone https://github.com/RuiSiang/PoW-Phalanx.git
# Install dependencies
npm install
# Configure settings
cp -n .env.example .env
# Edit .env
nano .env
# Transpile
npm run build
#############################################
# Set up redis server as database #
# install redis first #
# sudo apt-get install redis-server #
#############################################
npm start
Default endpoint: http://localhost:6000?token=token-for-type
The following are implemented with standard socket.io protocol. Base url is designated as endpoint, and message as the event. Calls are standarized in the following format:
{
"method": "call-method",
"arguments": ["array-of-parameters"],
}Passive endpoints consume a call and return data (call handled by phalanx socket server), active feeds emit a call to the client (call not handled by phalanx socket server).
| Method | Type | Scope | Arguments | Description |
|---|---|---|---|---|
| phlx_update_stats | passive endpoint | unicast | stats:Stat[] | Shield pushes new data to phalanx |
| phlx_update_settings | passive endpoint | unicast | stats:Config | Shield pushes new settings dump to phalanx |
| phlx_ban_ip | passive endpoint | unicast | [ip:string, seconds: uint] | Shield signals to phalanx that a new IP is banned |
| shld_ban_ip | active feed | broadcast | [ip:string, seconds: uint] | Phalanx broadcasts to shields that a new IP is banned |
| shld_fetch_stats | active feed | broadcast | N/A | Phalanx broadcasts to shields to signal a new data push |
| shld_fetch_settings | active feed | broadcast | N/A | Phalanx broadcasts to shields to signal a new settings dump |
| shld_set_config | active feed | broadcast | [key:string, value:any] | Phalanx broadcasts to shields to set a config parameter |
| shld_add_whitelist | active feed | broadcast | [token:string] | Phalanx broadcasts to shields to add a whitelist token |
| shld_remove_whitelist | active feed | broadcast | [token:string] | Phalanx broadcasts to shields to remove a whitelist token |
| shld_update_model | active feed | broadcast | TBD | Phalanx broadcasts to shields to update the edge security model |
| Method | Type | Scope | Arguments | Description |
|---|---|---|---|---|
| phlx_override_difficulty | passive endpoint | unicast | [difficulty:uint] | Controller asks phalanx to override difficulty |
| phlx_add_whitelist | passive endpoint | unicast | [token:string] | Controller asks phalanx to add new whitelist token |
| phlx_remove_whitelist | passive endpoint | unicast | [token:string] | Controller asks phalanx to remove whitelist token |
| phlx_update_model | passive endpoint | unicast | TBD | Controller pushes edge security model to phalanx to update on shields |
| ctrl_stats | active feed | broadcast | {stats:Stat[], whitelist: string[]} | Phalanx broadcasts current stats to controller |
| Method | Type | Scope | Arguments | Description |
|---|---|---|---|---|
| phlx_set_difficulty | passive endpoint | unicast | [difficulty:uint] | Model asks phalanx to set new difficulty |
| phlx_fetch_batch_stats | passive endpoint | unicast | [lastRow?:string] | Model requests phalanx to send batch stats |
| modl_batch_stats | active feed | unicast | stats:Stat[] | Phalanx sends batch stats to model |
| modl_backend_stats | active feed | broadcast | util:ResourceUtil | Phalanx redirects resource monitor stats on backend |
| modl_settings | active feed | broadcast | config:Config | Phalanx sends settings dump to model |
"stat-type":"client-id":"ISO-Timestamp"|"count"
i.e. ttl_req:aTqmrN0eKqaQa1nIAAAB:2022-06-14T01:55:00.014Z|10
| stat-type | Value | Unit |
|---|---|---|
| legit_req | accumulative legit request count | count |
| ttl_req | accumulative total request count | count |
| bad_nonce | accumulative bad nonce request count | count |
| ttl_waf | accumulative waf trigger count | count |
| ttl_solve_time | accumulated time of solved problems | milliseconds |
| prob_solved | number of problems solved | count |
i.e.
{
"cpuUtil": "0.27",
"memUtil": "14.22",
"uptime": "350"
}| stat-type | Value |
|---|---|
| cpuUtil | CPU utilization (percentage) |
| memUtil | RAM utilization (percentage) |
| uptime | machine uptime (seconds) |
Description: Get stats for model training
Request:
- Params: N/A
- Query:
- token: token for model connection (same as the one for socket)
Response:
- instances: object of stat entry arrays organized by client id and stat type (see example)
- settings: object of setting configurations for each client
- backend: resource stats on the backend site
Example Request
curl http://pow-phalanx:9000/stats?token=test-model-token
Example Response
{
"instances": {
"Do4a-RmsY-0zJmFeAAAB": {
"legit_req": ["1", "13", "22", "22", "23", "24", "24", "24", "24"],
"ttl_req": ["4", "16", "25", "27", "29", "30", "30", "31", "31"],
"bad_nonce": ["0", "0", "0", "0", "0", "0", "0", "0", "0"],
"ttl_waf": ["0", "0", "0", "0", "0", "0", "0", "1", "1"],
"ttl_solve_time": ["2544", "2544", "2544", "2544", "4647", "4647", "4647", "4647", "4647"],
"prob_solved": ["1", "1", "1", "1", "2", "2", "2", "2", "2"]
}
},
"settings": [
{
"settings:Do4a-RmsY-0zJmFeAAAB": "{\"session_key\":\"abcdefghijklmnop\",\"pow\":true,\"nonce_validity\":60000,\"difficulty\":13,\"backend_url\":\"http://webapp:80\",\"database_host\":\"redis1\",\"database_port\":6379,\"database_password\":\"\",\"rate_limit\":true,\"rate_limit_sample_minutes\":60,\"rate_limit_session_threshold\":100,\"rate_limit_ban_ip\":true,\"rate_limit_ip_threshold\":500,\"rate_limit_ban_minutes\":15,\"waf\":true,\"waf_url_exclude_rules\":\"\",\"waf_header_exclude_rules\":\"14,33,80,96,100\",\"waf_body_exclude_rules\":\"\",\"ssl\":false,\"ssl_cert_path\":\"tests/ssl/mock-cert.pem\",\"ssl_key_path\":\"tests/ssl/mock-key.pem\",\"socket\":true,\"socket_url\":\"http://pow-phalanx:6000\",\"socket_token\":\"test-subscription-token\"}"
}
],
"backend": "\"{\\\"cpuUtil\\\":\\\"0.30\\\",\\\"memUtil\\\":\\\"21.78\\\",\\\"uptime\\\":\\\"2591\\\"}\""
}Description: Get stats for model training
Request:
- Params: N/A
- Query:
- token: token for model connection (same as the one for socket)
- difficulty: difficulty to set (integer)
Response:
- 200: OK
- 400: Invalid
Example Request
curl http://pow-phalanx:9000/set?token=test-model-token&difficulty=13
Example Response
200 OK