Understanding-True-File-Types

User Objective

When dealing with files programmatically it is important that file types are identified correctly to eliminate the potential cases of file type masquerading, where files may be misrepresented with false extensions or MIME types.

Why?

By accurately identifying the true file type, the system can take appropriate actions to prevent security breaches, data corruption, or unintended processing of files. You can make informed decisions within your application based on the following scenarios:

Supported File Type

If the detected file type is within your list of supported file types, you can confidently proceed with the regular processing of the file within your system.

Unsupported File Type

If the detected file type falls under your list of unsupported file types, it is essential to take immediate action to prevent any further progression of that file within your system. In such cases, implement a "fail fast" mechanism to halt any further processing of the file, ensuring that your system is protected from handling potentially harmful or incompatible files.

File Type Masquerading

If the detected file type differs from the file's declared extension or MIME type, it may indicate file masquerading, where a malicious actor attempts to mislead the system. In such a critical scenario, consider taking more evasive actions to handle the file within your system. These actions may include isolating the file, running additional security checks, or notifying administrators for further investigation.

CDR Platform Events

1. You can initiate a request to the Glasswall CDR Platform API, choosing the appropriate endpoint based on the file type:

   • For binary files, the programmatic user uses the api/v3/cdr-file endpoint.
   • For base64-encoded files, the programmatic user uses the api/v3/cdr endpoint.

2. The Glasswall CDR Platform processes the request and conducts file type detection on the provided input.

3. To ensure that only file type detection is performed without any further actions you should include the response-content parameter in the URL with the value set to noRebuiltFile,noAnalysisReport. This activates the File Type Detection Only mode.

4. The Glasswall CDR Platform analyses the file using the Glasswall Embedded Engine to determine the true file type.

5. Upon successful detection, the Glasswall CDR Platform includes the identified true file type in the response header with the header key x-filetype.

6. You can then use the obtained true file type information for further processing, security checks, or any other necessary actions within your application or system.

API Authentication

To understand how to authenticate with the CDR Platform please see here

Request Construction

To process a binary file or a base64 encoded file using the Glasswall CDR Platform, follow the instructions below:

Binary File Processing

POST {baseUrl}/api/v3/cdr-file?response-content=noRebuiltFile,noAnalysisReport

Base64 Encoded File Processing

Submit the base64 encoded string in the request body to the following endpoint:

POST {baseUrl}/api/v3/cdr?response-content=noRebuiltFile,noAnalysisReport

Request Body Format

The body of the request should be in JSON format and include the base64 field containing the base64 encoded string of the file, and the fileName field specifying the original filename (including the appropriate file extension).

{
  "base64": "string",
  "fileName": "filename.pdf",
}

Note

• Replace {baseUrl} with the actual base URL of the Glasswall CDR Platform API.
• Correct auth header should be provided with each request
• Setting response-content to noRebuiltFile,noAnalysisReport in the URL ensures that only file type detection is performed without rebuilding the file or generating an analysis report.
• For binary file processing, use a multipart form post, while for base64 encoded file processing, provide the file content in the JSON request body with the appropriate filename.

Response Handling

After making a successful request, you will receive a 201 status code. However, when running the API in File Type Detect mode, there will be no file output in the response. To identify the true file type, inspect the response header and locate the x-filetype key. The value of this header will indicate the true file type.

• If the x-filetype value is unknown, it means that Glasswall was unable to identify the true file type for the given file.

• If the x-filetype value is 'txt', it indicates that the file contains purely UTF-8 or ASCII text.

Status: 201 Created
Headers:
  access-control-allow-origin: * 
  access-control-expose-headers: * 
  content-length: 0 
  content-type: text/plain 
  date: Thu,20 Jul 2023 10:55:46 GMT 
  strict-transport-security: max-age=31536000; includeSubDomains 
  x-applied-policy: service-dynamic 
  x-file-size: 301189 
  x-filetype: pdf 
  x-processing-id: 779b6828-1e1b-4148-9dc0-a3f1e38cb119 
  x-processing-status: rebuilt 

In the example above, the x-filetype value is pdf, indicating that the true file type is a PDF document.

For further details about possible error codes that can be returned by the API, refer to our API documentation. It provides comprehensive information allowing you to handle various error scenarios.

Expected Values

The output file types are associated with file type groups rather than individual extensions. With Glasswall's Embedded Engine multiple extensions are identified by a single value. To better comprehend the output values of the file type header, please refer to the table below:

File Type Value	Extensions
doc	.doc, .dot
xls	.xls, .xlt
ppt	.ppt, .pps, .pot
pdf	.pdf
docx	.docx, .docm, .dotx, .dotm
xlsx	.xlsx, .xltx, .xltm, .xlsm
pptx	.pptx, .pptm, .ppsx, .ppam, .potm, .ppsm, .potx
tiff	.tif, .tiff, .geotiff
svg	.svg
emf	.emf
wmf	.wmf
jpeg	.jpeg, .jpg, .jpe, .jif, .jfif, .jfi
png	.png
gif	.gif
bmp	.bmp, .dib

Objective Achievement

By implementing true file type detection in your application, you can ensure that your system processes files safely and efficiently, mitigating risks associated with unsupported or potentially malicious file types. Properly handling file type detection and reacting appropriately to different scenarios will help maintain the security and reliability of your application.

Quick Start

If you wish to take a look for yourself you can follow our quick start guide and use the CDR Platform yourself.