3.0.0a1 (#1523)

Alpha release of CTFd v3. 

# 3.0.0a1 / 2020-07-01

**General**

- CTFd is now Python 3 only
- Render markdown with the CommonMark spec provided by `cmarkgfm`
- Render markdown stripped of any malicious JavaScript or HTML.
  - This is a significant change from previous versions of CTFd where any HTML content from an admin was considered safe.
- Inject `Config`, `User`, `Team`, `Session`, and `Plugin` globals into Jinja
- User sessions no longer store any user-specific attributes.
  - Sessions only store the user's ID, CSRF nonce, and an hmac of the user's password
  - This allows for session invalidation on password changes
- The user facing side of CTFd now has user and team searching
- GeoIP support now available for converting IP addresses to guessed countries

**Admin Panel**

- Use EasyMDE as an improved description/text editor for Markdown enabled fields.
- Media Library button now integrated into EasyMDE enabled fields
- VueJS now used as the underlying implementation for the Media Library
- Fix setting theme color in Admin Panel
- Green outline border has been removed from the Admin Panel

**API**

- Significant overhauls in API documentation provided by Swagger UI and Swagger json
- Make almost all API endpoints provide filtering and searching capabilities
- Change `GET /api/v1/config/<config_key>` to return structured data according to ConfigSchema

**Themes**

- Themes now have access to the `Configs` global which provides wrapped access to `get_config`.
  - For example, `{{ Configs.ctf_name }}` instead of `get_ctf_name()` or `get_config('ctf_name')`
- Themes must now specify a `challenge.html` which control how a challenge should look.
- The main library for charts has been changed from Plotly to Apache ECharts.
- Forms have been moved into wtforms for easier form rendering inside of Jinja.
  - From Jinja you can access forms via the Forms global i.e. `{{ Forms }}`
  - This allows theme developers to more easily re-use a form without having to copy-paste HTML.
- Themes can now provide a theme settings JSON blob which can be injected into the theme with `{{ Configs.theme_settings }}`
- Core theme now includes the challenge ID in location hash identifiers to always refer the right challenge despite duplicate names

**Plugins**

- Challenge plugins have changed in structure to better allow integration with themes and prevent obtrusive Javascript/XSS.
  - Challenge rendering now uses `challenge.html` from the provided theme.
  - Accessing the challenge view content is now provided by `/api/v1/challenges/<challenge_id>` in the `view` section. This allows for HTML to be properly sanitized and rendered by the server allowing CTFd to remove client side Jinja rendering.
  - `challenge.html` now specifies what's required and what's rendered by the theme. This allows the challenge plugin to avoid having to deal with aspects of the challenge besides the description and input.
  - A more complete migration guide will be provided when CTFd v3 leaves beta
- Display current attempt count in challenge view when max attempts is enabled
- `get_standings()`, `get_team_stanadings()`, `get_user_standings()` now has a fields keyword argument that allows for specificying additional fields that SQLAlchemy should return when building the response set.
  - Useful for gathering additional data when building scoreboard pages
- Flags can now control the message that is shown to the user by raising `FlagException`
- Fix `override_template()` functionality

**Deployment**

- Enable SQLAlchemy's `pool_pre_ping` by default to reduce the likelihood of database connection issues
- Mailgun email settings are now deprecated. Admins should move to SMTP email settings instead.
- Postgres is now considered a second class citizen in CTFd. It is tested against but not a main database backend. If you use Postgres, you are entirely on your own with regards to supporting CTFd.
- Docker image now uses Debian instead of Alpine. See https://github.com/CTFd/CTFd/issues/1215 for rationale.
- `docker-compose.yml` now uses a non-root user to connect to MySQL/MariaDB
- `config.py` should no longer be editting for configuration, instead edit `config.ini` or the environment variables in `docker-compose.yml`

CTFd/api/v1/awards.py

@@ -1,18 +1,103 @@
+from typing import List
+
 from flask import request
 from flask_restx import Namespace, Resource
 
+from CTFd.api.v1.helpers.models import build_model_filters
+from CTFd.api.v1.helpers.request import validate_args
+from CTFd.api.v1.helpers.schemas import sqlalchemy_to_pydantic
+from CTFd.api.v1.schemas import APIDetailedSuccessResponse, APIListSuccessResponse
 from CTFd.cache import clear_standings
-from CTFd.utils.config import is_teams_mode
-from CTFd.models import Awards, db, Users
+from CTFd.constants import RawEnum
+from CTFd.models import Awards, Users, db
 from CTFd.schemas.awards import AwardSchema
+from CTFd.utils.config import is_teams_mode
 from CTFd.utils.decorators import admins_only
 
 awards_namespace = Namespace("awards", description="Endpoint to retrieve Awards")
 
+AwardModel = sqlalchemy_to_pydantic(Awards)
+
+
+class AwardDetailedSuccessResponse(APIDetailedSuccessResponse):
+    data: AwardModel
+
+
+class AwardListSuccessResponse(APIListSuccessResponse):
+    data: List[AwardModel]
+
+
+awards_namespace.schema_model(
+    "AwardDetailedSuccessResponse", AwardDetailedSuccessResponse.apidoc()
+)
+
+awards_namespace.schema_model(
+    "AwardListSuccessResponse", AwardListSuccessResponse.apidoc()
+)
+
 
 @awards_namespace.route("")
 class AwardList(Resource):
     @admins_only
+    @awards_namespace.doc(
+        description="Endpoint to list Award objects in bulk",
+        responses={
+            200: ("Success", "AwardListSuccessResponse"),
+            400: (
+                "An error occured processing the provided or stored data",
+                "APISimpleErrorResponse",
+            ),
+        },
+    )
+    @validate_args(
+        {
+            "user_id": (int, None),
+            "team_id": (int, None),
+            "type": (str, None),
+            "value": (int, None),
+            "category": (int, None),
+            "icon": (int, None),
+            "q": (str, None),
+            "field": (
+                RawEnum(
+                    "AwardFields",
+                    {
+                        "name": "name",
+                        "description": "description",
+                        "category": "category",
+                        "icon": "icon",
+                    },
+                ),
+                None,
+            ),
+        },
+        location="query",
+    )
+    def get(self, query_args):
+        q = query_args.pop("q", None)
+        field = str(query_args.pop("field", None))
+        filters = build_model_filters(model=Awards, query=q, field=field)
+
+        awards = Awards.query.filter_by(**query_args).filter(*filters).all()
+        schema = AwardSchema(many=True)
+        response = schema.dump(awards)
+
+        if response.errors:
+            return {"success": False, "errors": response.errors}, 400
+
+        return {"success": True, "data": response.data}
+
+    @admins_only
+    @awards_namespace.doc(
+        description="Endpoint to create an Award object",
+        responses={
+            200: ("Success", "AwardListSuccessResponse"),
+            400: (
+                "An error occured processing the provided or stored data",
+                "APISimpleErrorResponse",
+            ),
+        },
+    )
     def post(self):
         req = request.get_json()
 
@@ -57,6 +142,16 @@ class AwardList(Resource):
 @awards_namespace.param("award_id", "An Award ID")
 class Award(Resource):
     @admins_only
+    @awards_namespace.doc(
+        description="Endpoint to get a specific Award object",
+        responses={
+            200: ("Success", "AwardDetailedSuccessResponse"),
+            400: (
+                "An error occured processing the provided or stored data",
+                "APISimpleErrorResponse",
+            ),
+        },
+    )
     def get(self, award_id):
         award = Awards.query.filter_by(id=award_id).first_or_404()
         response = AwardSchema().dump(award)
@@ -66,6 +161,10 @@ class Award(Resource):
         return {"success": True, "data": response.data}
 
     @admins_only
+    @awards_namespace.doc(
+        description="Endpoint to delete an Award object",
+        responses={200: ("Success", "APISimpleSuccessResponse")},
+    )
     def delete(self, award_id):
         award = Awards.query.filter_by(id=award_id).first_or_404()
         db.session.delete(award)