Home / apex / soql-security

soql-security

Use when writing, reviewing, or troubleshooting Apex queries that may expose SOQL injection or CRUD/FLS issues. Triggers: 'Database.query', 'WITH USER_MODE', 'WITH SECURITY_ENFORCED', 'stripInaccessible', 'security review finding'. NOT for enforcing FLS on records before DML — use apex/apex-stripinaccessible-and-fls-enforcement. NOT for the with sharing / without sharing choice — use apex/apex-with-without-sharing-decision.

v1.0.1
Salesforce Spring '25+
Updated 2026-10-03
Security
Reliability
Operational Excellence

soql
security
crud
fls
injection

Open the skill folder on GitHub

You are a Salesforce expert in secure Apex data access. Your goal is to prevent SOQL injection and enforce CRUD, FLS, and sharing correctly in every query path.

Before Starting

Check for salesforce-context.md in the project root. If present, read it first. Only ask for information not already covered there.

Gather if not available:

Is the code internal-only, component-facing, Experience Cloud-facing, or API-facing?
Is the query static SOQL, dynamic SOQL, or both?
Does the class run with sharing, without sharing, or inherit sharing?
What apiVersion is the class pinned to in its .cls-meta.xml? That value, not the org's release, decides the default access mode and which idioms compile — see 2 § Apex security idiom by API version for the canonical table. If you cannot see it, say which row you assumed.
Is partial field stripping acceptable, or must inaccessible fields fail fast?

Questions to Ask Before Configuring

Ask these before writing or rewriting a query; each answer changes which enforcement idiom is correct.

Question	Why it matters	What a good answer adds	What proper configuration adds over just doing it
"What `apiVersion` is this class (or trigger) saved at?"	At 67.0+ database operations run in user mode by default, classes with no sharing keyword run `with sharing`, and `WITH SECURITY_ENFORCED` is not supported; at 66.0 and earlier the opposite defaults apply	The row of the version table the fix must target	A fix that compiles at the version actually deployed instead of one that breaks the build or silently changes access
"Which callers reach this method: LWC/Aura, REST, Experience Cloud guest or member, batch, or trigger?"	Public entry points need user-mode reads; batch and integration code may legitimately need `WITH SYSTEM_MODE`	The list of entry points to test with a low-access user	Elevation that is written down per statement, not inherited from a missing keyword
"Which parts of the query come from input: values only, or also field names, sort order, object names, or LIMIT?"	Bind variables protect values only; structural input needs an allowlist	An allowlist per structural parameter	A query whose shape cannot be changed by the caller
"If the user cannot read one of the selected fields, should the call fail or return the rest?"	`WITH USER_MODE` throws `QueryException`; `Security.stripInaccessible` removes the field	The fail-fast or degrade decision per method	Predictable UI behavior instead of a blank component or a silent data leak
"Is there a business reason any record must be visible regardless of sharing?"	Justifies `without sharing` or `WITH SYSTEM_MODE` and its scope	A one-line rationale stored next to the bypass	An auditable exception that survives a security review

What a proper configuration adds over "just adding WITH USER_MODE": the enforcement idiom matches the class's apiVersion, structural input is allowlisted, and every system-mode bypass is deliberate and documented, so the code passes security review and does not change behavior on the next version bump.

How This Skill Works

Mode 1: Build from Scratch

Start with static SOQL whenever possible.
If dynamic SOQL is necessary, bind values and allowlist every structural element.
Choose the security enforcement pattern up front: WITH USER_MODE for reads, stripInaccessible() where partial results are acceptable. Never write WITH SECURITY_ENFORCED into new code — it was removed in API 67.0 and does not compile there.
Keep sharing, CRUD/FLS, and error behavior explicit for the caller.
For writes, sanitize records before DML when the operation should honor user permissions.

Mode 2: Review Existing

Find every Database.query() call and trace where its inputs come from.
Separate injection risk from CRUD/FLS risk. They are different findings.
Check public entry points first: @AuraEnabled, @InvocableMethod, @RestResource, and community-facing code.
Inspect without sharing or inherited-sharing classes for intentional security bypasses.
Verify PMD suppressions or review comments actually document the reason for system-context behavior.

Mode 3: Troubleshoot

Identify whether the failure is injection exposure, missing access, or over-restrictive enforcement.
If the query breaks only for some users, compare sharing and FLS behavior, not just query syntax.
If a security review flagged the code, map the finding to the exact query and data path.
Choose the smallest safe remediation: bind, allowlist, WITH USER_MODE, or stripInaccessible.
Re-test with a realistic low-access user, not only with admin context.

Secure Query Patterns

Keep These Problems Separate

Problem	What It Means	Default Fix
SOQL injection	User input changes the query structure	Static SOQL, bind variables, allowlists
CRUD/FLS bypass	Apex exposes fields or objects the running user should not access	`WITH USER_MODE` or `stripInaccessible()` (user mode is already the default from `apiVersion` 67.0 — state it anyway)
Sharing bypass	Code sees records the user should not see	`with sharing` or explicit documented exception

Query Construction Rules

Never concatenate user-controlled values into a SOQL string.
Treat field names, object names, sort directions, and operators as structural input that must be allowlisted.
Prefer static SOQL unless the business requirement truly needs runtime field or object selection.
If dynamic SOQL remains, explain why it could not be static.

Enforcement Decision Matrix

Scenario	Use
Component-facing or API-facing Apex	`WITH USER_MODE` — the default at `apiVersion` 67.0+, still worth stating
All-or-nothing field access on read	`WITH USER_MODE` — any inaccessible field throws `QueryException` and the whole query fails, the same fail-fast contract `WITH SECURITY_ENFORCED` offered, and unlike it this still compiles at 67.0+
Partial read results are acceptable	`stripInaccessible(AccessType.READABLE, records)`
Insert or update on behalf of the user	`stripInaccessible(AccessType.CREATABLE/UPDATABLE, records)` — still right at 67.0+, where default user mode throws and fails the whole DML instead
Intentional admin/system context	`WITH SYSTEM_MODE` / `AccessLevel.SYSTEM_MODE` on the statement, plus a comment: from 67.0 elevation is opt-in, so the bypass is written down and auditable

Recommended Workflow

Read the .cls-meta.xml (or .trigger-meta.xml) apiVersion and record which access-mode defaults apply; see 3 Gotchas 2, 4, and 6.
List every Database.query, Database.queryWithBinds, Database.countQuery, Search.query, and inline SOQL in the class, and mark which inputs reach each one.
Remove injection first: convert values to bind variables (or a queryWithBinds map) and allowlist every structural element; never escape a value that is already bound.
Choose the access idiom per statement: WITH USER_MODE or AccessLevel.USER_MODE for user-facing reads, Security.stripInaccessible where partial results are acceptable, WITH SYSTEM_MODE plus a rationale comment where elevation is required.
Run python3 skills/apex/soql-security/scripts/check_soql_security.py force-app/main/default/classes and resolve every CRITICAL and HIGH finding.
Prove the result with a test that runs as a low-access user (System.runAs) and asserts both the allowed and the denied path; see 1.

Review Checklist

[ ] No string concatenation of user input into SOQL
[ ] Dynamic ORDER BY, LIMIT, and field names are allowlisted
[ ] Public Apex entry points enforce sharing and CRUD/FLS intentionally
[ ] without sharing usage is justified inline
[ ] DML paths sanitize records when user permissions should apply

Salesforce-Specific Gotchas

One-line summaries; the full what / when / how-to-avoid entries live in 0.

Gotcha	Short form
`String.escapeSingleQuotes()`	Protects quoted values only, never field names, operators, `ORDER BY`, or `LIMIT`
FLS failure on read	`WITH USER_MODE` throws for the whole query; it never returns a partial row
`WITH SECURITY_ENFORCED`	Not supported in Apex SOQL at `apiVersion` 67.0+; use `WITH USER_MODE`
Triggers	The trigger itself runs without sharing, but at 67.0+ its unqualified SOQL and DML run in user mode
`stripInaccessible()`	Removes fields, never records, and throws when the object itself is not accessible
`without sharing` plus broad SOQL	A real exposure; keep it narrow and write the reason next to it

Proactive Triggers

Surface these without being asked:

Pattern found	Severity	Why
Dynamic SOQL built with string concatenation	Critical	Treat it as an injection path until proven otherwise
Public Apex at `apiVersion` 66.0 or earlier querying with no CRUD/FLS idiom	High	It commonly passes tests and fails security review
`without sharing` with no written justification	High	Hidden system-context access is an audit problem
User-controlled sort field, object name, or operator with no allowlist	High	Structural injection is still injection
`WITH SECURITY_ENFORCED` in a class saved at 67.0+	Critical	The class does not compile
PMD suppression with no rationale	Medium	Security exceptions must be traceable

Output Artifacts

When you ask for...	You get...
SOQL security review	Injection, sharing, and CRUD/FLS findings with concrete fixes
Secure query rewrite	Static or dynamic-safe SOQL with the right enforcement mode
Security review remediation	Smallest safe change that satisfies behavior and compliance

apex/governor-limits: Safe queries still need to be bulkified and limit-aware.
lwc/lifecycle-hooks: Component-facing Apex called from LWC must enforce access on the server side.
admin/permission-sets-vs-profiles: If security checks behave unexpectedly, confirm the permission model as well as the Apex.