Skip to content

Database governance built for humans and agents — controlling changes and access across every major database.

feat(masking): support dynamic masking for MongoDB aggregate pipelines (#19470)

h3n4l375882b5f3d4
diff --git a/backend/api/v1/catalog_masking_mongodb.go b/backend/api/v1/catalog_masking_mongodb.go
index 7a27184bcd..c422782c66 100644
--- a/backend/api/v1/catalog_masking_mongodb.go
+++ b/backend/api/v1/catalog_masking_mongodb.go
@@ -19,6 +19,9 @@ func checkMongoDBRequestBlocked(analysis *mongoparser.MaskingAnalysis) error {
if operation == "" {
operation = "unknown"
}
+ if analysis.UnsupportedStage != "" {
+ return errors.Errorf("MongoDB aggregate() with stage %q on collection %q is not supported for dynamic masking. Supported operations are find(), findOne(), and aggregate() with shape-preserving stages only", analysis.UnsupportedStage, analysis.Collection)
+ }
return errors.Errorf("MongoDB operation %q on collection %q is not supported for dynamic masking in this release. Supported operations are find() and findOne()", operation+"()", analysis.Collection)
}
return nil
diff --git a/backend/api/v1/catalog_masking_mongodb_test.go b/backend/api/v1/catalog_masking_mongodb_test.go
index 8149c76a59..3fcb5ca6df 100644
--- a/backend/api/v1/catalog_masking_mongodb_test.go
+++ b/backend/api/v1/catalog_masking_mongodb_test.go
@@ -31,6 +31,7 @@ type mongodbCheckBlockedCase struct {
API string `yaml:"api"`
Operation string `yaml:"operation"`
Collection string `yaml:"collection"`
+ UnsupportedStage string `yaml:"unsupportedStage"`
WantError bool `yaml:"wantError"`
WantErrorContains string `yaml:"wantErrorContains"`
}
@@ -170,6 +171,8 @@ func mustMaskableAPI(t *testing.T, api string) mongoparser.MaskableAPI {
return mongoparser.MaskableAPIFindOne
case "unsupportedRead":
return mongoparser.MaskableAPIUnsupportedRead
+ case "aggregate":
+ return mongoparser.MaskableAPIAggregate
default:
require.Failf(t, "unknown api", "api %q not found", api)
return mongoparser.MaskableAPIUnsupported
@@ -200,9 +203,10 @@ func TestCheckMongoDBRequestBlocked(t *testing.T) {
var analysis *mongoparser.MaskingAnalysis
if !tc.AnalysisNil {
analysis = &mongoparser.MaskingAnalysis{
- API: mustMaskableAPI(t, tc.API),
- Operation: tc.Operation,
- Collection: tc.Collection,
+ API: mustMaskableAPI(t, tc.API),
+ Operation: tc.Operation,
+ Collection: tc.Collection,
+ UnsupportedStage: tc.UnsupportedStage,
}
}
err := checkMongoDBRequestBlocked(analysis)
diff --git a/backend/api/v1/sql_service.go b/backend/api/v1/sql_service.go
index 18c02dcdf7..2e8271f900 100644
--- a/backend/api/v1/sql_service.go
+++ b/backend/api/v1/sql_service.go
@@ -818,7 +818,7 @@ func queryRetry(
if analyzeErr != nil || analysis == nil || analysis.Collection == "" {
continue
}
- if analysis.API != mongoparser.MaskableAPIFind && analysis.API != mongoparser.MaskableAPIFindOne {
+ if analysis.API != mongoparser.MaskableAPIFind && analysis.API != mongoparser.MaskableAPIFindOne && analysis.API != mongoparser.MaskableAPIAggregate {
continue
}
diff --git a/backend/api/v1/test-data/mongodb_masking.yaml b/backend/api/v1/test-data/mongodb_masking.yaml
index d65c5d6f3d..53ab7df1e0 100644
--- a/backend/api/v1/test-data/mongodb_masking.yaml
+++ b/backend/api/v1/test-data/mongodb_masking.yaml
@@ -47,3 +47,17 @@ checkBlocked:
collection: users
wantError: true
wantErrorContains: aggregate()
+
+ - description: aggregate allowed
+ api: aggregate
+ operation: aggregate
+ collection: users
+ wantError: false
+
+ - description: aggregate with unsupported stage blocked
+ api: unsupportedRead
+ operation: aggregate
+ collection: users
+ unsupportedStage: "$group"
+ wantError: true
+ wantErrorContains: aggregate() with stage "$group"
diff --git a/backend/plugin/parser/mongodb/masking.go b/backend/plugin/parser/mongodb/masking.go
index ca5b40ca2e..69f7b31b0c 100644
--- a/backend/plugin/parser/mongodb/masking.go
+++ b/backend/plugin/parser/mongodb/masking.go
@@ -23,6 +23,8 @@ const (
MaskableAPIFindOne
// MaskableAPIUnsupportedRead means a read API that is blocked in Milestone 1.
MaskableAPIUnsupportedRead
+ // MaskableAPIAggregate means db.<collection>.aggregate(...) with only shape-preserving stages.
+ MaskableAPIAggregate
)
// MaskingAnalysis contains MongoDB statement data needed by masking checks.
@@ -31,6 +33,9 @@ type MaskingAnalysis struct {
Operation string
Collection string
PredicateFields []string
+ // UnsupportedStage is the first pipeline stage that prevents masking (e.g. "$group").
+ // Only set when API == MaskableAPIUnsupportedRead for aggregate pipelines.
+ UnsupportedStage string
}
// AnalyzeMaskingStatement analyzes a MongoDB shell statement for masking checks.
@@ -115,7 +120,7 @@ func classifyMaskingMethod(mc mongoparser.ICollectionMethodCallContext) *Masking
case mc.DistinctMethod() != nil:
return unsupportedReadAnalysis("distinct")
case mc.AggregateMethod() != nil:
- return unsupportedReadAnalysis("aggregate")
+ return classifyAggregateForMasking(mc.AggregateMethod())
case mc.GetIndexesMethod() != nil:
return unsupportedReadAnalysis("getIndexes")
case mc.StatsMethod() != nil:
@@ -340,3 +345,89 @@ func isLogicalOperator(key string) bool {
return false
}
}
+
+// shapePreservingAggregateStages contains aggregate pipeline stages whose output
+// documents retain the collection's original structure (fields are not reshaped).
+var shapePreservingAggregateStages = map[string]bool{
+ "$match": true,
+ "$sort": true,
+ "$limit": true,
+ "$skip": true,
+ "$sample": true,
+ "$addFields": true,
+ "$set": true,
+ "$unset": true,
+ "$geoNear": true,
+ "$setWindowFields": true,
+ "$fill": true,
+ "$redact": true,
+}
+
+func classifyAggregateForMasking(am mongoparser.IAggregateMethodContext) *MaskingAnalysis {
+ predicateFields, unsupportedStage := extractAggregatePredicateFields(am.Arguments())
+ if unsupportedStage != "" {
+ return &MaskingAnalysis{
+ API: MaskableAPIUnsupportedRead,
+ Operation: "aggregate",
+ UnsupportedStage: unsupportedStage,
+ }
+ }
+ return &MaskingAnalysis{
+ API: MaskableAPIAggregate,
+ Operation: "aggregate",
+ PredicateFields: predicateFields,
+ }
+}
+
+// extractAggregatePredicateFields walks the pipeline and returns predicate fields from $match stages.
+// The second return value is the first unsupported stage name, or "" if all stages are allowed.
+func extractAggregatePredicateFields(args mongoparser.IArgumentsContext) ([]string, string) {
+ if args == nil {
+ return nil, ""
+ }
+ allArgs := args.AllArgument()
+ if len(allArgs) == 0 {
+ return nil, ""
+ }
+
+ first := allArgs[0]
+ if first == nil || first.Value() == nil {
+ return nil, ""
+ }
+
+ arr := extractArrayValue(first.Value())
+ if arr == nil {
+ return nil, "unknown"
+ }
+
+ fields := make(map[string]struct{})
+ for _, elem := range arr.AllValue() {
+ doc := extractDocumentValue(elem)
+ if doc == nil {
+ return nil, "unknown"
+ }
+ pairs := doc.AllPair()
+ if len(pairs) == 0 {
+ continue
+ }
+ stageName := extractPairKey(pairs[0].Key())
+ if !shapePreservingAggregateStages[stageName] {
+ return nil, stageName
+ }
+ if stageName == "$match" {
+ stageDoc := extractDocumentValue(pairs[0].Value())
+ if stageDoc != nil {
+ collectPredicateFieldsFromDocument(stageDoc, "", fields)
+ }
+ }
+ }
+
+ if len(fields) == 0 {
+ return nil, ""
+ }
+ result := make([]string, 0, len(fields))
+ for field := range fields {
+ result = append(result, field)
+ }
+ return result, ""
+}
diff --git a/backend/plugin/parser/mongodb/masking_test.go b/backend/plugin/parser/mongodb/masking_test.go
index e707b5e462..c2dc6fe2a1 100644
--- a/backend/plugin/parser/mongodb/masking_test.go
+++ b/backend/plugin/parser/mongodb/masking_test.go
@@ -61,14 +61,132 @@ func TestAnalyzeMaskingStatement(t *testing.T) {
},
},
{
- description: "aggregate is unsupported read api",
+ description: "aggregate with shape-preserving stages",
statement: `db.users.aggregate([{$match: {name: "alice"}}])`,
want: &MaskingAnalysis{
- API: MaskableAPIUnsupportedRead,
+ API: MaskableAPIAggregate,
+ Operation: "aggregate",
+ Collection: "users",
+ PredicateFields: []string{"name"},
+ },
+ },
+ {
+ description: "aggregate with multiple shape-preserving stages",
+ statement: `db.users.aggregate([{$match: {status: "active"}}, {$sort: {name: 1}}, {$limit: 10}])`,
+ want: &MaskingAnalysis{
+ API: MaskableAPIAggregate,
+ Operation: "aggregate",
+ Collection: "users",
+ PredicateFields: []string{"status"},
+ },
+ },
+ {
+ description: "aggregate match with logical operators",
+ statement: `db.users.aggregate([{$match: {$or: [{age: {$gt: 18}}, {name: "alice"}]}}])`,
+ want: &MaskingAnalysis{
+ API: MaskableAPIAggregate,
+ Operation: "aggregate",
+ Collection: "users",
+ PredicateFields: []string{"age", "name"},
+ },
+ },
+ {
+ description: "aggregate with addFields and unset",
+ statement: `db.users.aggregate([{$addFields: {fullName: "test"}}, {$unset: "ssn"}])`,
+ want: &MaskingAnalysis{
+ API: MaskableAPIAggregate,
+ Operation: "aggregate",
+ Collection: "users",
+ },
+ },
+ {
+ description: "aggregate with empty pipeline",
+ statement: `db.users.aggregate([])`,
+ want: &MaskingAnalysis{
+ API: MaskableAPIAggregate,
+ Operation: "aggregate",
+ Collection: "users",
+ },
+ },
+ {
+ description: "aggregate with no arguments",
+ statement: `db.users.aggregate()`,
+ want: &MaskingAnalysis{
+ API: MaskableAPIAggregate,
Operation: "aggregate",
Collection: "users",
},
},
+ {
+ description: "aggregate with $group is unsupported",
+ statement: `db.users.aggregate([{$group: {_id: "$status"}}])`,
+ want: &MaskingAnalysis{
+ API: MaskableAPIUnsupportedRead,
+ Operation: "aggregate",
+ Collection: "users",
+ UnsupportedStage: "$group",
+ },
+ },
+ {
+ description: "aggregate with $project is unsupported",
+ statement: `db.users.aggregate([{$match: {name: "alice"}}, {$project: {name: 1}}])`,
+ want: &MaskingAnalysis{
+ API: MaskableAPIUnsupportedRead,
+ Operation: "aggregate",
+ Collection: "users",
+ UnsupportedStage: "$project",
+ },
+ },
+ {
+ description: "aggregate with $lookup is unsupported",
+ statement: `db.users.aggregate([{$lookup: {from: "orders", localField: "_id", foreignField: "userId", as: "orders"}}])`,
+ want: &MaskingAnalysis{
+ API: MaskableAPIUnsupportedRead,
+ Operation: "aggregate",
+ Collection: "users",
+ UnsupportedStage: "$lookup",
+ },
+ },
+ {
+ description: "aggregate with $out is unsupported",
+ statement: `db.users.aggregate([{$match: {status: "active"}}, {$out: "activeUsers"}])`,
+ want: &MaskingAnalysis{
+ API: MaskableAPIUnsupportedRead,
+ Operation: "aggregate",
+ Collection: "users",
+ UnsupportedStage: "$out",
+ },
+ },
+ {
+ description: "aggregate with $unwind is unsupported",
+ statement: `db.users.aggregate([{$unwind: "$tags"}])`,
+ want: &MaskingAnalysis{
+ API: MaskableAPIUnsupportedRead,
+ Operation: "aggregate",
+ Collection: "users",
+ UnsupportedStage: "$unwind",
+ },
+ },
+ {
+ description: "aggregate with $replaceRoot is unsupported",
+ statement: `db.users.aggregate([{$replaceRoot: {newRoot: "$contact"}}])`,
+ want: &MaskingAnalysis{
+ API: MaskableAPIUnsupportedRead,
+ Operation: "aggregate",
+ Collection: "users",
+ UnsupportedStage: "$replaceRoot",
+ },
+ },
+ {
+ description: "aggregate with $count is unsupported",
+ statement: `db.users.aggregate([{$count: "total"}])`,
+ want: &MaskingAnalysis{
+ API: MaskableAPIUnsupportedRead,
+ Operation: "aggregate",
+ Collection: "users",
+ UnsupportedStage: "$count",
+ },
+ },
{
description: "countDocuments is unsupported read api",
statement: `db.users.countDocuments({})`,