TransactionSecurityPolicy Metadata Type for Shield Security

Why the TransactionSecurityPolicy Metadata Type Prevents Data Exfiltration#

Even when a user legitimately has Read access to 50,000 Customer Contacts to perform their daily job, they should not be allowed to export all 50,000 rows to a CSV file or run an unthrottled SOAP/REST query() from an unknown IP address.

Part of Salesforce Shield (Real-Time Event Monitoring), TransactionSecurityPolicy (transactionSecurityPolicies/<Name>.transactionSecurityPolicy-meta.xml) intercepts synchronous platform events in real time (ReportEvent, ApiEvent, ListViewEvent, LoginEvent, FileEventStore) and takes immediate enforcement actions:

• Block (<block>true</block>): Aborts the report export, API query, or login before data leaves the org and displays a custom <blockMessage>.
• Multi-Factor Authentication (<twoFactorAuthentication>true</twoFactorAuthentication>): Prompts for step-up MFA on supported events.
• Real-Time Notifications (<notifications>): Sends email and in-app alerts to Security Operations.

Key Metadata Fields on TransactionSecurityPolicy#

Real-World XML & Apex Example: Blocking Mass Report Exports#

1. Apex TxnSecurity.EventCondition Class (classes/BlockMassReportExportCondition.cls)#

global class BlockMassReportExportCondition implements TxnSecurity.EventCondition {
    public boolean evaluate(SObject event) {
        if (event instanceof ReportEvent) {
            ReportEvent reportEvt = (ReportEvent) event;
            return reportEvt.Operation == 'ReportExported'
                && reportEvt.RowsProcessed > 2000;
        }
        return false;
    }
}

2. Policy Metadata (transactionSecurityPolicies/Block_Mass_Report_Exports.transactionSecurityPolicy-meta.xml)#

<?xml version="1.0" encoding="UTF-8"?>
<TransactionSecurityPolicy xmlns="http://soap.sforce.com/2006/04/metadata">
    <action>
        <block>true</block>
        <endSession>false</endSession>
        <freezeUser>false</freezeUser>
        <notifications>
            <inApp>true</inApp>
            <sendEmail>true</sendEmail>
            <user>secops.admin@acme.example.com</user>
        </notifications>
        <twoFactorAuthentication>false</twoFactorAuthentication>
    </action>
    <active>true</active>
    <apexClass>BlockMassReportExportCondition</apexClass>
    <blockMessage>Exporting reports with more than 2,000 rows is restricted by corporate security policy. Please contact InfoSec for an approved extract.</blockMessage>
    <description>Blocks any report export exceeding 2,000 rows and alerts Security Operations.</description>
    <developerName>Block_Mass_Report_Exports</developerName>
    <eventName>ReportEvent</eventName>
    <masterLabel>Block Mass Report Exports</masterLabel>
    <type>CustomApexPolicy</type>
</TransactionSecurityPolicy>

Querying TransactionSecurityPolicy via SOQL#

SELECT Id, DeveloperName, MasterLabel, EventName, Type, State,
       ApexPolicy.Name, BlockMessage, LastModifiedDate
FROM TransactionSecurityPolicy
ORDER BY EventName, DeveloperName

Frequently asked questions

What is the difference between CustomApexPolicy and CustomConditionBuilderPolicy in TransactionSecurityPolicy?

A CustomConditionBuilderPolicy evaluates declarative conditions stored in an underlying Flow metadata component, whereas a CustomApexPolicy invokes an Apex class implementing the TxnSecurity.EventCondition interface for complex SOQL or procedural logic.

Which real-time events can a TransactionSecurityPolicy monitor?

The eventName field supports ReportEvent, ApiEvent, ListViewEvent, LoginEvent, LoginAsEvent, FileEventStore, BulkApiResultEventStore, PermissionSetEventStore, AdminSetupEvent, and threat events like ApiAnomalyEventStore, ReportAnomalyEventStore, and SessionHijackingEventStore.

Why does deploying a TransactionSecurityPolicy fail across Sandboxes when notifications are configured?

Inside action.notifications, the user field stores a hardcoded Salesforce username (such as secops@acme.com). If that exact username does not exist in the target Sandbox, deployment fails unless replaced via sfdx-project.json string replacements.

Can you query TransactionSecurityPolicy definitions in SOQL?

Yes. Both standard SOQL and the Tooling API allow querying TransactionSecurityPolicy to inspect DeveloperName, MasterLabel, State, EventName, Type, ApexPolicyId, and BlockMessage.