This repository has been archived by the owner on Mar 3, 2020. It is now read-only.
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
* Live Sync API
* Introducing the Live Sync API.
* The Live Sync API allows administrators to import game activity in near-real-time. Users can link their accounts on one or more FBCTF platform instances and their scores will be automatically imported into the systems that have been linked.
* The primary use-case revolves around event aggregation across multiple FBCTF instances. Event organizers can now separate FBCTF instances and combine scores into one global scoreboard.
* The Live Sync API will import Levels, Categories, Scoring Events, and Hint Usage. Scores are automatically calculated, and bonuses are updated to ensure accurate scoring across linked FBCTF instances.
* Administrators determine which systems, if any, are linked.
* Users must link their account in order for their activity to be synced.
* The UI/UX of FBCTF has been updated to include a mechanism for users to configure their Live Sync credentials.
* Users cannot obtain hints or capture levels on the importing system.
* The API is JSON based and the schema is generalized so that it can leveraged by other platforms or external processes. So data can be synced from non-FBCTF platforms.
* The importing script will automatically handle country conflicts (if two systems have the same country selected for a level).
* USER GUIDE (Documentation):
* Users must first have an account on all FBCTF instances they wish to link.
* The user must then login and access the game board.
* From the navigation menu, the user should select "Account."
* The user must then set a Live Sync username and password. The Live Sync username and password must not be their login credentials. In fact, users are prohibited from using their account password as their Live Sync password.
* The user would repeat the above steps for each FBCTF instance they wish to link. The Live Sync credentials must be the same on each FBCTF instance or their accounts will not be linked.
* ADMIN GUIDE (Documentation):
* The admin is free to sync as many platforms as their desire. Additionally the admin may import from as many API sources as their desire.
* The admin will need to launch the "live import" script, on any importing systems, from the command-line:
* `hhvm -vRepo.Central.Path=/var/run/hhvm/.hhvm.hhbc_liveimport /var/www/fbctf/src/scripts/liveimport.php <Space Delimited URLs to API Endpoints> <Sleep Between Cycles> <Disable SSL Certificate Verification> <Show Debug Messages>`
* Disabling of the SSL Verification and Debugging are both optional. The URL(s) and Sleep time are required arguments.
* EXAMPLE: `hhvm -vRepo.Central.Path=/var/run/hhvm/.hhvm.hhbc_liveimport /var/www/fbctf/src/scripts/liveimport.php "https://10.10.10.101/data/livesync.php https://10.10.10.102/data/livesync.php https://10.10.10.103/other/platform/api" 300 true true`
* API SCHEMA (JSON):
* JSON:
[{"active":true,"type":"flag","title":"Example Level 1","description":"This is the first example level.","entity_iso_code":"TJ","category":"None","points":100,"bonus":30,"bonus_dec":10,"penalty":10,"teams":{"fbctf:user1:$2y$12$a1T4KyqqxADi3YIJ7M2sf.VoSHz6qMBx.zrxAIvZnD8de95EsLeny":{"timestamp":"2017-02-17 02:20:22","capture":true,"hint":false}}}]
* Explained (Formatted output for readability - the actually data must be in valid JSON format):
[0] => Array
(
[active] => 1 // Level Status (Enabled/Disabled)
[type] => flag // Level Type (Flag or Quiz)
[title] => Example Level 1 // Level Name
[description] => This is the first example level. // Level Description
[entity_iso_code] => US // Country Code (Mapping)
[category] => None // Level Category
[points] => 100 // Points
[bonus] => 30 // Bonus Points
[bonus_dec] => 10 // Bonus Point Decrement
[penalty] => 0 // Hint Cost
[teams] => Array
(
[fbctf:user3:$2y$12$GIR7V0Q2OMDv8cTTOnzKVpGYgR4.pWTsPRHtZ3yenKZ9JxOabx4m2] => Array // Live Sync Type, Live Sync Username, Live Sync Key (Hash)
(
[timestamp] => 2017-02-17 01:09:24 // Activity Timestamp
[capture] => 1 // Capture Status
[hint] => // Hint Used
)
)
)
* Example (Formatted output for readability - the actually data must be in valid JSON format):
Array
(
[0] => Array
(
[active] => 1
[type] => flag
[title] => Example Level 1
[description] => This is the first example level.
[entity_iso_code] => US
[category] => None
[points] => 100
[bonus] => 30
[bonus_dec] => 10
[penalty] => 0
[teams] => Array
(
)
)
[1] => Array
(
[active] => 1
[type] => flag
[title] => Example Level 2
[description] => This is the second example level.
[entity_iso_code] => OM
[category] => None
[points] => 100
[bonus] => 30
[bonus_dec] => 10
[penalty] => 0
[teams] => Array
(
[fbctf:user1:$2y$12$n.VmlNNwxmZ/OkGGuhVhFeX0VExAgjoaYzyetLCIemSXN/yxWXLyO] => Array
(
[timestamp] => 2017-02-17 01:01:49
[capture] => 1
[hint] => 1
)
[fbctf:user2:$2y$12$GIDv8cR7V0nzKVpQ2OMTTOGYgR4.pWTxOPRH9abtsJZ3yenKZx4m2] => Array
(
[timestamp] => 2017-02-17 01:21:13
[capture] => 1
[hint] => 1
)
)
)
[2] => Array
(
[active] => 1
[type] => flag
[title] => Example Level 3
[description] => This is the third example level.
[entity_iso_code] => MA
[category] => None
[points] => 100
[bonus] => 30
[bonus_dec] => 10
[penalty] => 0
[teams] => Array
(
[fbctf:user2:$2y$12$GIDv8cR7VpQ2OM0nzKVTTOGYgR4.pWTxOabtsPRH9JZ3yenKZx4m2] => Array
(
[timestamp] => 2017-02-17 01:18:45
[capture] => 1
[hint] =>
)
[fbctf:user1:$2y$12$n.VmlNNwxmZ/OkGGuhVhFeXYzExAg0VoajyetLCIemSXN/yxWXLyO] => Array
(
[timestamp] => 2017-02-17 01:01:41
[capture] => 1
[hint] =>
)
)
)
[3] => Array
(
[active] => 1
[type] => flag
[title] => Example Level 4
[description] => This is the second example level.
[entity_iso_code] => RO
[category] => None
[points] => 100
[bonus] => 30
[bonus_dec] => 10
[penalty] => 0
[teams] => Array
(
[fbctf:user3:$2y$12$GIDv8cR7V02OnzKVpQMTTOGYgR4.pWTsPOabtZRH9Jx3yenKZx4m2] => Array
(
[timestamp] => 2017-02-17 01:09:24
[capture] => 1
[hint] =>
)
)
)
)
* TO DO (Enhancements):
* Implemented alternative Live Sync key/authentication mechanisms, such as: Facebook Login, OAuth, etc.
* Improve the processing of Bases/Progressive scoring.
* Integrate password strength enforcement for the Live Sync credentials.
* * Added unit tests for Live Sync to TeamTest
* * Updated unit tests for the Live Sync API.
* Added Google OAuth to Live Sync API
* Google OAuth can now be used with the Live Sync when the exporting system provides the "google_oauth" type and provides the email address of the user in base64 encoded form.
* Added Google OAuth UI/UX. If enabled, this allows a user to link their Google account to their FBCTF account using Google OAuth. The user simply navigates to the account page and clicks the "Link Your Google Account" button and completes the sign-in/authorization process.
* Administrators must enable Google OAuth. When disabled the option does not appear for the users. To enable Google OAuth the administrator must first create a Google API account and then place the API secrets file on the system (in a non-web directory). The administrator would then set the full path to the API secrets file in the settings.ini file, within the GOOGLE_OAUTH_FILE field.
* The Live Sync API has been updated to handle the "google_oauth" type case.
* The liveimport.php script has been updated to set default values for some of the API fields. The following fields are mandatory:
* title
* description
* points
* teams
* The live import code has also been updated to ensure duplicate levels, when using a combination of non-defined and defined countries, are not generated.
* The project now requires google/apiclient ^2.0 from composer. Updated composer.json and composer.lock to define the new dependencies.
* Minor formatting updates.
* * Ensure mandatory fields are set, gracefully skip when they are not.
* Refined Live Import CLI Options and Updated Google OAuth Data
* The live sync import script (livesync.php) now utilizes `getopts()` to provide more user-friendly option input to the command-line script. The script will provide a help message upon usage without the required field(s). Here is the help message text:
```
Usage:
hhvm -vRepo.Central.Path=/var/run/hhvm/.hhvm.hhbc_liveimport /var/www/fbctf/src/scripts/liveimport.php
--url <Sync URL> [Switched allowed multiple times. Optionally provide custom HTTP headers after URL, pipe delimited]
--sleep <Time to Sleep Between Cycles> [Default: 300]
--disable-ssl-verification [Optional: Disables SSL Certification Verification]
--debug [Optional: Enables Debug Output]
```
* Custom HTTP Headers are now supported via the `url` CLI argument, using a pipe (`|`) delimiter. Multiple headers may be provided by the user.
* Users of the live sync import script (livesync.php) must provide at minimum the `url` argument. Multiple URLs are allowed in order to import from more than one host. Additionally, users may specify custom HTTP headers as necessary per-URL.
* The `sleep`, `disable-ssl-verification`, and `debug` arguments are optional. By default the script will sleep for 300 seconds between imports; this may be changed with the `sleep` option. By default the script will enforce SSL security and verification, however there are times when this may need to be disabled. SSL Verification can be disabled with the `disable-ssl-verification` option. The `debug` option provides a detailed output of the scripts activity; unless `debug` is used, the script will provide no output unless an error is encountered.
* Here are some example usages of the liveimport.php script:
* Single URL, 30 second cycles:
`hhvm -vRepo.Central.Path=/var/run/hhvm/.hhvm.hhbc_liveimport /var/www/fbctf/src/scripts/liveimport.php --url "https://10.10.10.101/data/livesync.php" --sleep 30`
* Multiple URLs, 90 second cycles, Disable SSL Verification:
`hhvm -vRepo.Central.Path=/var/run/hhvm/.hhvm.hhbc_liveimport /var/www/fbctf/src/scripts/liveimport.php --disable-ssl-verification --url "https://10.10.10.101/data/livesync.php" --url "https://10.10.10.103/data/livesync.php" --sleep 90`
* Multiple URLs, One Custom HTTP Header, Debug Enabled:
`hhvm -vRepo.Central.Path=/var/run/hhvm/.hhvm.hhbc_liveimport /var/www/fbctf/src/scripts/liveimport.php --debug --url "https://10.10.10.101/data/livesync.php" --url "https://10.10.10.102/data/livesync.php|X-API-KEY: f4f0d2154f338fd8edb38fc3839f22dd"`
* The live sync import script (livesync.php) now performs XSSI filtering on the returned JSON and logs an error message if the JSON data is missing or malformed.
* Inverse conditions within the live sync import script (livesync.php) have been reformatted to provide clearer readability.
* The Google OAuth Live Sync key has been switched from the user's email address to their Google Profile ID. This value does not need to be encoded.
* Minor Updates
* Added a specific redirect URL for the Google OAuth process. This will ensure the user is redirected back to the same (sub)domain they came from. This is primarily useful if the FBCTF instance is accessible from multiple domains or subdomains (like www). The redirect URL must still be authorized in the Google API settings/console.
* Added a date/time output for the debug mode of the live import script.
* Set the modal title to a static value.- Loading branch information
1 parent
300091c
commit 0b7ca09