Understanding-and-using-policy
User Objective
Achieve seamless process flow optimisation by leveraging Glasswall's CDR Platform, empowering you to efficiently manage content management policies.
Why?
Enhance your content management capabilities with Glasswall's CDR Platform and Embedded engine. By defining content management policies, or policies for short, you gain access to a powerful set of configuration flags that govern the treatment of files and their contents during the CDR process.
In diverse system scenarios, the need for varying content management flags may arise. The CDR Platform's flexibility empowers you to apply different sets of flags for each situation, accommodating multiple use cases within a single system and efficiently handling edge case scenarios without manual intervention.
The advantages of the CDR Platform extend beyond submitting diverse policies at the point of request. You can now manage policies programmatically, eliminating the overhead of storing and maintaining changes between versions. With a unified integration point, you can easily manage policies by name and effortlessly request file rebuilds, streamlining your processes and reducing the amount of code needed for executing requests against the CDR Platform.
API Documentation
To use a defined policy in a request, you have two options. First, you can create a named policy using the provided API calls. For a detailed understanding of these API calls, please refer to the API documentation.
Alternatively, if you prefer a more straightforward approach, you can directly use the default policy that comes pre-installed with all CDR Platform installations. Managing the default policy is made easy through the CDR Platform portal, which offers a user-friendly interface to customize it according to your needs.
By setting the default policy through the portal, it will automatically be utilised in any API call for file rebuilding, provided that a dynamic or named policy is not explicitly specified.
Feel free to explore the API documentation for a comprehensive understanding of how to manipulate policies using the available API calls. For quick and convenient policy adjustments, the CDR Platform portal offers an intuitive solution.
API Authentication
To understand how to authenticate with the CDR Platform please see here
CDR Platform Flow of Events
-
To create a new policy, simply use the following API call in the policy management API, providing the desired policy settings in the request body.
POST api/v1/policies/{policyname}
{
"status": "enabled",
"policySettings": {
"contentManagementFlags": {
"pdfContentManagement": {
"acroform": "sanitise",
"digitalSignatures": "sanitise",
"embeddedFiles": "sanitise",
"embeddedImages": "sanitise",
"externalHyperlinks": "sanitise",
"internalHyperlinks": "sanitise",
"javascript": "sanitise",
"metadata": "sanitise",
"actionsAll": "sanitise",
"retainExportedStreams": 1,
"valueOutsideReasonableLimits": 1
},
"wordContentManagement": {
"dynamicDataExchange": "sanitise",
"embeddedFiles": "sanitise",
"embeddedImages": "sanitise",
"externalHyperlinks": "sanitise",
"hiddenData": "allow",
"internalHyperlinks": "sanitise",
"macros": "sanitise",
"metadata": "sanitise",
"reviewComments": "sanitise",
"trackedChanges": "sanitise"
},
"excelContentManagement": {
"connections": "sanitise",
"dynamicDataExchange": "sanitise",
"embeddedFiles": "sanitise",
"embeddedImages": "sanitise",
"externalHyperlinks": "sanitise",
"hiddenData": "allow",
"internalHyperlinks": "sanitise",
"macros": "sanitise",
"metadata": "sanitise",
"reviewComments": "sanitise",
"trackedChanges": "sanitise"
},
"powerPointContentManagement": {
"embeddedFiles": "sanitise",
"embeddedImages": "sanitise",
"externalHyperlinks": "sanitise",
"hiddenData": "allow",
"internalHyperlinks": "sanitise",
"macros": "sanitise",
"metadata": "sanitise",
"reviewComments": "sanitise",
"slideNotes": "sanitise"
},
"svgConfig": {
"hyperlinks": "sanitise",
"foreignObjects": "sanitise",
"scripts": "sanitise"
},
"webpConfig": {
"metadata": "sanitise"
},
"tiffConfig": {
"geoTiff": "sanitise"
},
"archiveConfig": {
"bmp": 1,
"doc": 1,
"docx": 1,
"emf": 1,
"gif": 1,
"jpg": 1,
"wav": 1,
"elf": 1,
"pe": 1,
"mp4": 1,
"mpg": 1,
"pdf": 1,
"png": 1,
"ppt": 1,
"pptx": 1,
"tif": 1,
"wmf": 1,
"xls": 1,
"xlsx": 1,
"mp3": 1,
"rtf": 1,
"coff": 1,
"macho": 1,
"svg": 1,
"webp": 1,
"unknown": 1
}
}
}
}
-
If you prefer not to create a new policy but instead update the existing default policy, you can achieve this by sending the new policy settings in the request body to the following endpoint:
PUT api/v1/policies/default -
Once you have successfully created or edited your policy, you can now utilize them in your requests within the CDR Platform. Refer to the next section to learn how to apply a specific policy to a rebuild request.
By following these steps, you can efficiently manage policies and tailor them to suit your requirements in the CDR Platform.
Request Construction
The CDR Platform offers three distinct ways to utilise policies: Default, Named, and Dynamic. Each approach can be applied to specific CDR Endpoints as described below:
Default Policy
The default policy is the pre-installed policy that comes with the CDR Platform. While it can be edited, if no other policy is specified in the request, this default policy is used during file processing. If the Policy Management API is not available, a "sanitise all" policy is applied as a fallback – applying the most restrictive policy possible. Sending a request to the following endpoints without content management flags in the request body will apply the default policy to the processing:
POST api/v3/cdr-file
POST api/v3/cdr
Named Policy
When employing a named policy, you submit a request with the policy name as a query parameter in the URL. The platform will then look up the named policy, which should have been previously created, and apply it accordingly. To achieve this, send requests to the following URLs:
POST api/v3/cdr-file?policyName={policyname}
POST api/v3/cdr?policyName={policyname}
As the default policy is essentially a named policy, you can pass 'default' as the query parameter value to apply the default policy during processing.
Dynamic Policy
The dynamic policy refers to passing the policy settings directly at the time of the request. You can make a request to the following URLs and include the Content Management Flags as part of the request body to apply those specific settings during file processing. A dynamic policy takes precedence over any other policy if a policy name is also provided.
POST api/v3/cdr-file
POST api/v3/cdr
{
"ContentManagementFlags": {
"PdfContentManagement": {
"Acroform": 1,
"ActionsAll": 1,
"EmbeddedFiles": 1,
"EmbeddedImages": 1,
"ExternalHyperlinks": 1,
"InternalHyperlinks": 1,
"Javascript": 1,
"Metadata": 1,
"DigitalSignatures": 1,
"ValueOutsideReasonableLimits": 1,
"RetainExportedStreams": 1
},
"WordContentManagement": {
"DynamicDataExchange": 1,
"EmbeddedFiles": 1,
"EmbeddedImages": 1,
"ExternalHyperlinks": 1,
"HiddenData": 0,
"InternalHyperlinks": 1,
"Macros": 1,
"Metadata": 1,
"ReviewComments": 1,
"TrackedChanges": 1
},
"ExcelContentManagement": {
"DynamicDataExchange": 1,
"EmbeddedFiles": 1,
"EmbeddedImages": 1,
"ExternalHyperlinks": 1,
"HiddenData": 1,
"InternalHyperlinks": 1,
"Macros": 1,
"Metadata": 1,
"ReviewComments": 1,
"TrackedChanges": 1,
"Connections": 1
},
"PowerPointContentManagement": {
"EmbeddedFiles": 1,
"EmbeddedImages": 1,
"ExternalHyperlinks": 1,
"HiddenData": 1,
"InternalHyperlinks": 1,
"Macros": 1,
"Metadata": 1,
"ReviewComments": 1,
"SlideNotes": 1
},
"ArchiveConfig": {
"bmp": 1,
"doc": 1,
"docx": 1,
"emf": 1,
"gif": 1,
"jpg": 1,
"wav": 1,
"elf": 1,
"pe": 1,
"mp4": 1,
"mpg": 1,
"pdf": 1,
"png": 1,
"ppt": 1,
"pptx": 1,
"tif": 1,
"wmf": 1,
"xls": 1,
"xlsx": 1,
"mp3": 1,
"rtf": 1,
"coff": 1,
"macho": 1,
"svg": 1,
"webp": 1,
"unknown": 1
},
"SvgConfig": {
"ForeignObjects": 1,
"Hyperlinks": 1,
"Scripts": 1
},
"WebpConfig": {
"Metadata": 1
},
"TiffConfig": {
"GeoTiff": 1
}
}
}
By understanding and utilising these three policy approaches, you can effectively tailor the CDR Platform's behaviour to meet your specific requirements during file processing.
Response Handling
As part of the response, you will receive not only the processed file as an output but also a set of headers. Among these headers, one key header is of particular interest: x-applied-policy. Observing this header will allow you to determine which policy was applied during the processing. The x-applied-policy header can take on the following values:
- (name) the named policy that was applied
- default the configured default policy was applied
- service-dynamic a dynamic policy was submitted with the request and applied
- glasswall-fallback the fallback policy was applied since the specified policy was not available
By examining the value in the x-applied-policy header, you can easily discern which policy was used to process the file, whether it was the default policy, a named policy, or a dynamic policy. This information is helpful for tracking and understanding the policy application in the CDR Platform.
Objective Achievement
With the capability to apply various policies in different situations, the CDR Platform empowers you to define policies tailored to your specific needs. By assigning names to these policies, you can seamlessly process different files with distinct rules, based on the business situation or the flow of your application. Some potential scenarios where this functionality proves valuable include:
Email Flow
In an email flow scenario, you could gain the flexibility to process files differently based on the sender and receiver. By employing named policies, you can define unique rules for files originating from specific senders or destined for particular recipients. This way, you can apply appropriate policies for different email sources and destinations.
File Upload
By utilizing named policies, you can create rules tailored to specific IP addresses or ranges, ensuring that files from different sources undergo distinct processing based on their origins.
User Roles and Permissions
In a multi-user environment, you may have different user roles with varying levels of access and permissions. Based on the user's role, you might want to apply different policies to files uploaded or processed by them. For example, administrators could have more permissive policies for handling files, while regular users might have stricter policies in place.
Geographical Locations
Depending on the geographical location of the user or the server handling file uploads, you may wish to enforce specific policies to comply with local regulations or data protection laws. Different regions may have distinct data privacy requirements, and applying location-based policies ensures compliance with regional laws.
With these versatile policy management capabilities, you can efficiently handle varying file processing requirements within your application, adapting to different contexts and scenarios. The ability to apply named policies empowers you to optimize file handling and security measures according to the specific needs of your business and the unique circumstances your application encounters.
Quick Start
If you wish to take a look for yourself you can follow our quick start guide and use the CDR Platform yourself.