Corelan Cybersecurity Research

It may sound a bit extraordinary, but I needed to have the ability to change attachment filenames while they were being processed by the transport service on Exchange. I can’t really tell you why I needed this functionality, but I guess there could be many reasons to do so. (e.g. zip files should be renamed to .zip.renamed  so they need to be saved to disk first, renamed and then opened, and so on).  Anyways, I could not find a way to do this with the Exchange built-in features, so I had to write my own custom transport agent to do this.

The agent is written in C#, uses .Net Framework 3.5, uses the native MS Exchange API’s and works fine with Exchange 2007 (I’ve only tested SP1) and 2010 (beta 1). The dll has been compiled for x64 (64bit) systems only.

Putting the files in place

You can download the dll file from the link below. (As usual, you need to be logged in to download the file)

This transport agent needs to be installed on all HUB transport servers in the organization, so the following procedure needs to be executed on all HUB transport servers :

1. Create folder structure

Create a folder called “pveattachrename” on drive C: (yes, it needs to be drive C:, and yes the folder needs to have this name)

In this ‘”pveattachrename” folder, create the following subfolders :

• bin
• config
• rules
• log
• temp

(The 2 last folders : ‘log’ and ‘temp’ are the only folders that could grow in size (well, in fact, the log folder could grow, the temp folder is used to temporarily save attachments, but all temp files should get cleaned after processing an email). You will be able to move these 2 folders to another location. I’ll explain you how to do this later on).

Extract the downloaded dll file in the bin folder.

2. Set security on folder structure

The Exchange transport agent will run with “Network Service” permissions and needs to be able to read from the bin/config/rules folders, and write into the pveattachrename, the log and the temp folders. The easiest way to set the permissions is by allowing Network Service to read and write in the entire “pveattachrename” folder (and subfolders of course)

Transport agent configuration

1. Set application configuration parameters

In the config folder, create a file called config.cfg

This file can contain 3 configuration entries :

• verbose=true  ( or  verbose=false)
• workingfolder=
• logfolder=

The “workingfolder” and “logfolder” entries are optional. If you don’t specifiy anything, the logfiles will be written to c:\pveattachrename\log and the temp folder will be c:\pveattachrename\temp.  If you decide to move the log and/or temp folders, make sure to grant the “Network Service” account read/write permissions to these folders. If you do specify a workingfolder or logfolder entry, don’t set a slash at the end of the path.

If you set verbose to true, you will be able to see – in detail – what happens when the transport agent functions are called.  This is a good way to troubleshoot issues, but the logfiles can grow quite large.  The log files will rotate every week, and log files older than 6 months should get removed automatically.  If you set verbose to false, only application errors will be written into the log files.

(Note : keep everything in lowercase, and don’t use spaces before and after the = symbol)

Example :

verbose=true
workingfolder=e:\pverenametemp
logfolder=d:\pverenamelog

2. Create rules

In the rules folder, you can create as many rule files as you want.  A rule file is a file that has extension .rule, and contains the following entries :

• extension=
• renameaction=
• from=

(The ‘from’ parameter is optional. If you don’t want to use it, just leave it out of the file)

Extension : here you can specify the attachment extension you want to apply the rename action to. You can only specify one attachment filename extension.  I recommend to include the . (dot) in the extension. So suppose you want to rename zip files, you need to specify

extension=.zip

Renameaction : With this parameter, you can specify how the renamed attachment should look like. There are a couple of variable that can be used :

%filename% : will be replaced the original filename, without extension

%random% : will be replaced by a 8 character random string

%timestamp% : will be replaced by a date- & timestring that looks like this :   YYYYMMDD_HHMMSS

%date% : will be replaced by a datestring that looks like this : YYYYMMDD

%time% : will be replaced by a timestring that looks like this : HHMMSS

So suppose you want to rename zip files to .zip.save.me.first, rename the filename and add some random characters to the filename, you need to set the renameaction parameter to :

renameaction=%filename%_renamed_%random%.zip.save.me.first

Note : If the new filename becomes longer than 150 characters, only the first 140 characters will be used, and a new random string will be added (to make it unique again). So if you really want to have the original filename at the beginning of the filename, make sure to put %filename% at the beginning of the renameaction

From : You can specify one keyword (a domain name or email address). Only emails originating from this domain name or email address will be processed by the rule. If you have multiple email addresses or domain names, you’ll have to create multiple rule files.  (I may change this in the future, but this is how it works today). If you don’t want to filter on “From” email address/domain name, then don’t set the “from” keyword.

Save the file. I usually give the .rule file a filename that reflects the attachment extension inside the .rule file, but if you want to name them 01.rule, 02.rule, or something else…. feel free.

(By the way, make sure to verify that the .rule file is not saved as .rule.txt (and ‘hide extension for known filetypes’ is turned on). Everything may look ok, but the rules would not be used if they don’t have the .rule extension.

Every time an email is processed by the agent, a new Header is stamped onto the message. This will ensure that an email that is sent across multiple Transport servers will not get processed twice.  This header is called X-PVEAttachRename and contains a GUID-alike string.  If you have verbose logging enabled, you can use this GUID string to look up what happened to the email in the log file by searching for this string.

Installing & enabling the agent

Open MS Exchange Management Shell (Powershell) and run the following cmdlet : (pay attention, case sensitive !)

Install-TransportAgent
   -name "PVE Attachment Rename"
   -TransportAgentFactory "pveAttachRenameTptAgent.PVEAttachRenameTptAgentFactory"
   -AssemblyPath C:\pveattachrename\bin\pveAttachRenameTptAgent.dll

(put everything on one line !)

The output should look like this :

Close Powershell (This is required to make the agent work). Open Powershell again and restart the Transport service :

Restart-Service MSExchangeTransport

When the service has restarted, enable the Transport Agent, and restart the MS Exchange Transport Service again :

Enable-TransportAgent -id "PVE Attachment Rename"
Restart-Service MSExchangeTransport

The agent is now active.

Support/Bugs/Feedback

Please use the forum at http://www.corelan.be:8800/index.php/forum/pve-exchange-attachment-rename-tpt-agent/ to post your support questions, file bugs or just provide some feedback about the agent.

Thanks for dropping by (again).

© 2009 – 2021, Peter Van Eeckhoutte (corelanc0d3r). All rights reserved.

Similar/Related posts:

Free tool – Attachment filtering with Exchange 2007/2010 (custom transport agent) Exchange 2007 – Multi Account Domain to Single Resource Forest replication with IIFP and custom Rules Extension Fixing Exchange 2007 Offline Address Book generation (oalgen) and distribution issues Exchange Server 2010 available worldwide Exchange 2007 Administration : Policies and limits