Files

User-generated content often includes media such as images, videos, audio, or other files. UGC Guard supports two main approaches for handling media files in reports.

1. Uploading Files to UGC Guard

The recommended method is to upload media files directly to UGC Guard when submitting a report. This approach offers several advantages:

• Uploaded files cannot be deleted or modified by the original creator.
• Files remain unchanged, preserving their state at the time of reporting.
• Authenticated UGC Guard users can access these files without additional authentication steps.

Consider the following:

• The maximum upload size is 50MB (hosted version only).
• Media files are automatically deleted after a retention period, starting when a report is escalated or rejected.
• Uploading files results in duplicate storage, as files exist both on your system and within UGC Guard.

Refer to the API client documentation for your preferred programming language for upload instructions.

Once the media file is uploaded, add the file id to the media_identifiers list in the Content object.

2. Proxying Media

Alternatively, you can keep media files on your own service and provide UGC Guard with a URL to access them. There are two ways to implement this:

2.1 No Authentication

DANGER

Without authentication, anyone can access your media endpoint. This may expose sensitive information and could have legal implications, especially if the reported content is illegal in certain jurisdictions.

If your media is already publicly accessible, this is the simplest way to provide media files to UGC Guard. Instead of uploading, add the media file's URL to the media_identifiers list in the Content object.

INFO

Ensure your endpoint supports the GET method.

2.2 Authentication Using Webhook Signing

TIP

This is the preferred method for proxying media.

To keep media files on your service securely, implement an endpoint that supports GET requests and verifies signed requests from UGC Guard. UGC Guard will sign requests using the action secret associated with the report's type.

Example implementation in FastAPI:

@router.get("/media/{media_id}")
async def get_media_api(
    media_id: str,
    request: Request,
    x_action_signature: Annotated[str | None, Header()] = None,
):
    """
    Returns the media with the given media_id.
    """
    payload = request.headers.get('X-Payload', None)

    if not payload:
        raise HTTPException(
            status_code=400,
            detail="X-Payload header is required",
            headers={"X-Action-Error": "X-Payload header is required"},
        )

    payload = json.loads(payload)

    if not _verify_signature(x_action_signature, payload):
        raise invalid_signature_response

    # Optionally, check if the timestamp in the payload is close to datetime.now()

    media_bytes, content_type, content_disposition = get_media(media_id)

    if media_bytes is None:
        raise HTTPException(status_code=404, detail="Media not found")

    return StreamingResponse(
        iter([media_bytes]),
        media_type=content_type,
        headers={
            "content-disposition": content_disposition
            if content_disposition
            else f'attachment; filename="{media_id}"'
        },
    )

def _verify_signature(signature: str, payload: dict) -> bool:
    """
    Verifies the signature of the payload using the provided secret.
    """
    secret = os.getenv("webhook_secret")
    if not secret:
        print("No secret configured for UGC Guard webhook.")
        return False

    if not signature:
        print("No signature provided for UGC Guard webhook.")
        return False

    # Verify the signature using the GuardClient's verify_signature method
    valid_signature = GuardClient.verify_signature(payload, secret, signature)

    return valid_signature

To use this method, add the URL of your secured endpoint to the media_identifiers list in the Content object.

2.3 Advantages and Disadvantages of Proxying

Advantages:

• Media files are stored only once, saving disk space and resources.
• Reports are created faster since files do not need to be uploaded again.

Disadvantages:

• Media files could be altered or deleted on your system if not quarantined after reporting.
• Setting up an authenticated media endpoint for UGC Guard requires additional effort and configuration.

2.4 Proxy Cache

If proxied media files are smaller than 4 MB, UGC Guard will cache them automatically and serve them instead of requesting them from your service again. The retention of this cache is about 5 minutes.

Send the correct response status

Media is only cached, if the response is of status 200. So your service should only return 200 if the media file is also returned with the response. Else the cache will contain a defect response and serve it to UGC Guard instances!

Unsecure Locations

UGC Guard (SaaS) cannot access files from your local development environment or any resource that is not publicly available via https. For security reasons, proxying media files from unsecured or local sources is not permitted on the hosted platform.

If you are running a self-hosted instance and need to enable proxying from localhost or other unsecured locations, refer to the configuration guide for instructions.

3. Rentention

When uploading files to UGC Guard, they are not kept indefinitely.

• Media files that are not linked to any report are deleted on the next day.
• Media files linked to reports that are rejected are deleted after a minimum of 7 days following the rejection.
• Media files linked to reports that are escalated are deleted after a minimum of 180 days following the escalation.

These retention periods are not fixed. When self-hosting you can change these periods in the .env file. If you are using our hosted solution, you can contact us to change the retention period for individual files or for files in general.