diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/admin/request_filtering_modes.md | 33 | ||||
| -rw-r--r-- | docs/api/swagger.yaml | 248 |
2 files changed, 279 insertions, 2 deletions
diff --git a/docs/admin/request_filtering_modes.md b/docs/admin/request_filtering_modes.md new file mode 100644 index 000000000..78f5dfe77 --- /dev/null +++ b/docs/admin/request_filtering_modes.md @@ -0,0 +1,33 @@ +# HTTP Request Header Filtering Modes + +GoToSocial currently offers 'block', 'allow' and disabled HTTP request header filtering modes, which can be set using the `advanced-header-filter-mode` setting in the config.yaml, or using the `GTS_ADVANCED_HEADER_FILTER_MODE` environment variable. These are described below. + +!!! warning + HTTP request header filtering is an advanced setting. If you are not well versed in the uses and intricacies of HTTP request headers, you may break federation or even access to your own instance by changing these. + + HTTP request header filtering is also still considered "experimental". It should do what it says on the box, but it may cause bugs or edge cases to appear elsewhere, we're not sure yet! + + Management via settings panel is TBA. Until then you will need to manage these directly via API endpoints. + +## Disabled header filtering mode (default) + +When `advanced-header-filter-mode` is set to `""`, i.e. an empty string, all request header filtering will be disabled. + +## Block filtering mode + +When `advanced-header-filter-mode` is set to `"block"`, your instance will accept HTTP requests as normal (pending API token checks, HTTP signature checks etc), with the exception of matching block header filters you have explicitly created via the settings panel. + +In block mode, an allow header filter can be used to override an existing block filter, providing an extra level of granularity. + +A request in block mode will be accepted if it is EXPLICITLY ALLOWED OR NOT EXPLICITLY BLOCKED. + +## Allow filtering mode + +When `advanced-header-filter-mode` is set to `"allow"`, your instance will only accept HTTP requests for which a matching allow header filter has been explicitly created via the settings panel. All other requests will be refused. + +In allow mode, a block header filter can be used to override an existing allow filter, providing an extra level of granularity. + +A request in allow mode will only be accepted if it is EXPLICITLY ALLOWED AND NOT EXPLICITLY BLOCKED. + +!!! danger + Allow filtering mode is an extremely restrictive mode that will almost certainly prevent many (legitimate) clients from being able to access your instance, including yourself. You should only enable this mode if you know exactly what you're trying to achieve.
\ No newline at end of file diff --git a/docs/api/swagger.yaml b/docs/api/swagger.yaml index ae2a5453c..500355ac3 100644 --- a/docs/api/swagger.yaml +++ b/docs/api/swagger.yaml @@ -1193,6 +1193,20 @@ definitions: type: object x-go-name: Field x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model + headerFilterCreateRequest: + properties: + header: + description: The HTTP header to match against (e.g. User-Agent). + type: string + x-go-name: Header + regex: + description: The header value matching regular expression. + type: string + x-go-name: Regex + title: HeaderFilterRequest is the form submitted as a POST to create a new header filter entry (allow / block). + type: object + x-go-name: HeaderFilterRequest + x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model hostmeta: description: 'See: https://www.rfc-editor.org/rfc/rfc6415.html#section-3' properties: @@ -2108,13 +2122,17 @@ definitions: x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model pollRequest: properties: - expires_in: + ExpiresIn: description: |- Duration the poll should be open, in seconds. If provided, media_ids cannot be used, and poll[options] must be provided. format: int64 type: integer - x-go-name: ExpiresIn + expires_in: + description: |- + Duration the poll should be open, in seconds. + If provided, media_ids cannot be used, and poll[options] must be provided. + x-go-name: ExpiresInI hide_totals: description: Hide vote counts until the poll ends. type: boolean @@ -4563,6 +4581,232 @@ paths: summary: Send a generic test email to a specified email address. tags: - admin + /api/v1/admin/header_allows: + get: + operationId: headerFilterAllowsGet + responses: + "200": + description: All "allow" header filters currently in place. + schema: + items: + $ref: '#/definitions/headerFilter' + type: array + "400": + description: bad request + "401": + description: unauthorized + "403": + description: forbidden + "404": + description: not found + "500": + description: internal server error + security: + - OAuth2 Bearer: + - admin + summary: Get all "allow" header filters currently in place. + tags: + - admin + post: + consumes: + - application/json + - application/xml + - application/x-www-form-urlencoded + description: |- + The parameters can also be given in the body of the request, as JSON, if the content-type is set to 'application/json'. + The parameters can also be given in the body of the request, as XML, if the content-type is set to 'application/xml'. + operationId: headerFilterAllowCreate + produces: + - application/json + responses: + "200": + description: The newly created "allow" header filter. + schema: + $ref: '#/definitions/headerFilter' + "400": + description: bad request + "401": + description: unauthorized + "403": + description: forbidden + "500": + description: internal server error + security: + - OAuth2 Bearer: + - admin + summary: Create new "allow" HTTP request header filter. + tags: + - admin + /api/v1/admin/header_allows/{id}: + delete: + operationId: headerFilterAllowDelete + parameters: + - description: Target header filter ID. + in: path + name: id + required: true + type: string + responses: + "202": + description: Accepted + "400": + description: bad request + "401": + description: unauthorized + "403": + description: forbidden + "404": + description: not found + "500": + description: internal server error + security: + - OAuth2 Bearer: + - admin + summary: Delete the "allow" header filter with the given ID. + tags: + - admin + get: + operationId: headerFilterAllowGet + parameters: + - description: Target header filter ID. + in: path + name: id + required: true + type: string + responses: + "200": + description: The requested "allow" header filter. + schema: + $ref: '#/definitions/headerFilter' + "400": + description: bad request + "401": + description: unauthorized + "403": + description: forbidden + "404": + description: not found + "500": + description: internal server error + security: + - OAuth2 Bearer: + - admin + summary: Get "allow" header filter with the given ID. + tags: + - admin + /api/v1/admin/header_blocks: + get: + operationId: headerFilterBlocksGet + responses: + "200": + description: All "block" header filters currently in place. + schema: + items: + $ref: '#/definitions/headerFilter' + type: array + "400": + description: bad request + "401": + description: unauthorized + "403": + description: forbidden + "404": + description: not found + "500": + description: internal server error + security: + - OAuth2 Bearer: + - admin + summary: Get all "allow" header filters currently in place. + tags: + - admin + post: + consumes: + - application/json + - application/xml + - application/x-www-form-urlencoded + description: |- + The parameters can also be given in the body of the request, as JSON, if the content-type is set to 'application/json'. + The parameters can also be given in the body of the request, as XML, if the content-type is set to 'application/xml'. + operationId: headerFilterBlockCreate + produces: + - application/json + responses: + "200": + description: The newly created "block" header filter. + schema: + $ref: '#/definitions/headerFilter' + "400": + description: bad request + "401": + description: unauthorized + "403": + description: forbidden + "500": + description: internal server error + security: + - OAuth2 Bearer: + - admin + summary: Create new "block" HTTP request header filter. + tags: + - admin + /api/v1/admin/header_blocks/{id}: + delete: + operationId: headerFilterBlockDelete + parameters: + - description: Target header filter ID. + in: path + name: id + required: true + type: string + responses: + "202": + description: Accepted + "400": + description: bad request + "401": + description: unauthorized + "403": + description: forbidden + "404": + description: not found + "500": + description: internal server error + security: + - OAuth2 Bearer: + - admin + summary: Delete the "block" header filter with the given ID. + tags: + - admin + get: + operationId: headerFilterBlockGet + parameters: + - description: Target header filter ID. + in: path + name: id + required: true + type: string + responses: + "200": + description: The requested "block" header filter. + schema: + $ref: '#/definitions/headerFilter' + "400": + description: bad request + "401": + description: unauthorized + "403": + description: forbidden + "404": + description: not found + "500": + description: internal server error + security: + - OAuth2 Bearer: + - admin + summary: Get "block" header filter with the given ID. + tags: + - admin /api/v1/admin/instance/rules: post: consumes: |