Identify true file types to reduce risk

When handling files electronically, it's important to identify their file type correctly. This eliminates the threat of file type masquarading, where files may be misrepresented with false extensions or MIME types.

Our API correctly identifies the true file type, so that the system can take appropriate actions to prevent security breaches, data corruption, or unintended processing of files.

Once the correct file type is identified, you can make informed decisions within your application based on the following scenarios:

Supported File Type

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

Unsupported File Type

If the detected file type falls under the 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, it is recommended that you 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 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.

Glasswall Halo Events

How to make a request to Glasswall Halo:

1. Begin by initiating a request to the Glasswall Halo API, choosing the appropriate endpoint based on the file type:

• For binary files, use the api/v3/cdr-file endpoint.
• For Base64 encoded files, use the api/v3/cdr endpoint.

2. Glasswall Halo processes the request and conducts file type detection on the original file.

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

4. Glasswall Halo analyses the file using the Glasswall Embedded Engine to determine the true file type.

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

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

API Authentication

Glasswall Halo supports two types of authentication: Basic and Bearer. Before making any request, you must authenticate using the appropriate scheme based on your configuration.

Basic

If your system is configured with Basic authentication, you need to obtain an Organisation ID and token from the system administrator. Combine these values in the format <OrganisationId>:<Token> and then Base64 encode them. The resulting encoded value should be included in the request header as follows:

Authorization: Basic ZGVtbzpwQDU1dzByZA==

Bearer

For Bearer authentication, you will require a Bearer token obtained from your identity provider. Once you have obtained the token, include it in the request header as follows:

Authorization: Bearer ZGVtbzpwQDU1dzByZA==

Note: ensure that you use the appropriate authentication method as per your system's configuration. Using the correct authentication ensures successful access to the Glasswall Halo API and prevents any authorization issues.

Learn more about authenticating Glasswall Halo

Request Construction

To process a binary file or a Base64 encoded file using Glasswall Halo, follow the instructions below:

Binary File Processing

Submit the binary string in the Request body to the following endpoint:

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 Halo 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. There you can also find comprehensive information for handling 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:

Summary

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 infrastructure.

Quick Start

To try Glasswall Halo yourself, please refer to our Quick Start Guide.