SONARPY-3102: Rule S7613: Returned Values Must Be JSON Serializable. (#408)

joke1196 · sonartech · commit 11a73a9f55a5 · 2025-08-04T09:08:08.000Z
GitOrigin-RevId: bc9a24fc289f418167a750142a0676d70a7934ad
diff --git a/python-checks/src/main/java/org/sonar/python/checks/AwsLambdaReturnValueAreSerializableCheck.java b/python-checks/src/main/java/org/sonar/python/checks/AwsLambdaReturnValueAreSerializableCheck.java
@@ -0,0 +1,257 @@
+/*
+ * SonarQube Python Plugin
+ * Copyright (C) 2011-2025 SonarSource SA
+ * mailto:info AT sonarsource DOT com
+ *
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the Sonar Source-Available License Version 1, as published by SonarSource SA.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+ * See the Sonar Source-Available License for more details.
+ *
+ * You should have received a copy of the Sonar Source-Available License
+ * along with this program; if not, see https://sonarsource.com/license/ssal/
+ */
+package org.sonar.python.checks;
+
+import java.util.Optional;
+import java.util.Set;
+import java.util.stream.Stream;
+import org.sonar.check.Rule;
+import org.sonar.plugins.python.api.PythonSubscriptionCheck;
+import org.sonar.plugins.python.api.SubscriptionContext;
+import org.sonar.plugins.python.api.TriBool;
+import org.sonar.plugins.python.api.symbols.ClassSymbol;
+import org.sonar.plugins.python.api.symbols.Symbol;
+import org.sonar.plugins.python.api.symbols.Usage;
+import org.sonar.plugins.python.api.tree.CallExpression;
+import org.sonar.plugins.python.api.tree.DictionaryLiteral;
+import org.sonar.plugins.python.api.tree.Expression;
+import org.sonar.plugins.python.api.tree.FunctionDef;
+import org.sonar.plugins.python.api.tree.KeyValuePair;
+import org.sonar.plugins.python.api.tree.ListLiteral;
+import org.sonar.plugins.python.api.tree.Name;
+import org.sonar.plugins.python.api.tree.QualifiedExpression;
+import org.sonar.plugins.python.api.tree.RegularArgument;
+import org.sonar.plugins.python.api.tree.ReturnStatement;
+import org.sonar.plugins.python.api.tree.Tree;
+import org.sonar.plugins.python.api.tree.Tuple;
+import org.sonar.python.checks.utils.AwsLambdaChecksUtils;
+import org.sonar.python.checks.utils.Expressions;
+import org.sonar.python.tree.TreeUtils;
+import org.sonar.python.types.v2.TypeCheckBuilder;
+import org.sonar.python.types.v2.TypeCheckMap;
+
+@Rule(key = "S7613")
+public class AwsLambdaReturnValueAreSerializableCheck extends PythonSubscriptionCheck {
+
+  private static final String MESSAGE = "Fix the return value to be JSON serializable.";
+  private static final String SECONDARY_LOCATION_MESSAGE = "The non-serializable value is set here.";
+
+  // This should be moved to type checking once SONARPY-3223 is done
+  private static final Set<String> NON_SERIALIZABLE_FQNS = Set.of(
+    "datetime.datetime.now",
+    "datetime.datetime.utcnow",
+    "datetime.datetime.today",
+    "datetime.datetime.fromtimestamp",
+    "datetime.datetime.utcfromtimestamp",
+    "datetime.date",
+    "datetime.date.today",
+    "datetime.date.fromtimestamp",
+    "datetime.time");
+
+  // Method names that indicate serialization
+  private static final Set<String> SERIALIZATION_METHOD_NAMES = Set.of(
+    "to_dict",
+    "dict",
+    "asdict",
+    "serialize",
+    "json");
+
+  private TypeCheckBuilder listType;
+  private TypeCheckBuilder setType;
+
+  private TypeCheckMap<Object> serializationFunctions;
+  private TypeCheckMap<Object> nonSerializableTypes;
+
+  record IssueLocation(Tree mainLocation, Optional<Tree> secondaryLocation) {
+    public IssueLocation(Tree mainLocation) {
+      this(mainLocation, Optional.empty());
+    }
+  }
+
+  @Override
+  public void initialize(Context context) {
+    context.registerSyntaxNodeConsumer(Tree.Kind.FILE_INPUT, this::initializeTypeChecker);
+    context.registerSyntaxNodeConsumer(Tree.Kind.RETURN_STMT, this::checkReturnStatement);
+  }
+
+  private void initializeTypeChecker(SubscriptionContext ctx) {
+    listType = ctx.typeChecker().typeCheckBuilder().isBuiltinWithName("list");
+
+    setType = ctx.typeChecker().typeCheckBuilder().isBuiltinWithName("set");
+
+    var object = new Object();
+    serializationFunctions = new TypeCheckMap<>();
+    serializationFunctions.put(ctx.typeChecker().typeCheckBuilder().isTypeWithFqn("dataclasses.asdict"), object);
+    serializationFunctions.put(ctx.typeChecker().typeCheckBuilder().isTypeWithFqn("json.dumps"), object);
+    serializationFunctions.put(ctx.typeChecker().typeCheckBuilder().isTypeWithFqn("json.loads"), object);
+
+    nonSerializableTypes = new TypeCheckMap<>();
+    nonSerializableTypes.put(setType, object);
+    nonSerializableTypes.put(ctx.typeChecker().typeCheckBuilder().isTypeOrInstanceWithName("re.Pattern"), object);
+    nonSerializableTypes.put(ctx.typeChecker().typeCheckBuilder().isTypeOrInstanceWithName("decimal.Decimal"), object);
+    // Covers all io hierachy: StringIO, BytesIO etc...
+    nonSerializableTypes.put(ctx.typeChecker().typeCheckBuilder().isInstanceOf("typing.IO"), object);
+    nonSerializableTypes.put(ctx.typeChecker().typeCheckBuilder().isBuiltinWithName("complex"), object);
+    nonSerializableTypes.put( ctx.typeChecker().typeCheckBuilder().isBuiltinWithName("bytes"), object);
+    nonSerializableTypes.put( ctx.typeChecker().typeCheckBuilder().isBuiltinWithName("bytearray"), object);
+    nonSerializableTypes.put( ctx.typeChecker().typeCheckBuilder().isBuiltinWithName("frozenset"), object);
+  }
+
+  private void checkReturnStatement(SubscriptionContext ctx) {
+    ReturnStatement returnStmt = (ReturnStatement) ctx.syntaxNode();
+
+    Tree parentFunction = TreeUtils.firstAncestorOfKind(returnStmt, Tree.Kind.FUNCDEF);
+    if (parentFunction == null) {
+      return;
+    }
+
+    FunctionDef function = (FunctionDef) parentFunction;
+    if (!AwsLambdaChecksUtils.isLambdaHandler(ctx, function)) {
+      return;
+    }
+
+    if (returnStmt.expressions().isEmpty()) {
+      return;
+    }
+
+    Expression returnExpr = returnStmt.expressions().get(0);
+    getNonSerializableExpr(returnExpr)
+      .forEach(location -> {
+        PreciseIssue issue = ctx.addIssue(location.mainLocation, MESSAGE);
+        location.secondaryLocation.ifPresent(secondaryLocation -> issue.secondary(secondaryLocation, SECONDARY_LOCATION_MESSAGE));
+      });
+  }
+
+  private Stream<IssueLocation> getNonSerializableExpr(Expression expr) {
+    switch (expr.getKind()) {
+      case CALL_EXPR:
+        return getNonSerializableCallExpr((CallExpression) expr);
+      case DICTIONARY_LITERAL:
+        return getNonSerializableInDictionaryLiteral((DictionaryLiteral) expr);
+      case LIST_LITERAL:
+        return getNonSerializableInListLiteral((ListLiteral) expr);
+      case TUPLE:
+        return getNonSerializableInTuple((Tuple) expr);
+      case NAME:
+        return getNonSerializableFromName((Name) expr);
+      default:
+        return getNonSerializableFromTypeOrFqn(expr);
+    }
+  }
+
+  private Stream<IssueLocation> getNonSerializableCallExpr(CallExpression callExpr) {
+    // First check if this is a serialization method call like user.to_dict()
+    if (isSerializationMethodCall(callExpr)) {
+      return Stream.of();
+    }
+
+    Symbol calleeSymbol = callExpr.calleeSymbol();
+    String fullyQualifiedName = calleeSymbol != null ? calleeSymbol.fullyQualifiedName() : null;
+    if (fullyQualifiedName == null) {
+      return Stream.of();
+    }
+    // Check if this is a list call converting non-serializable types to serializable ones
+    if (listType.check(callExpr.callee().typeV2()).equals(TriBool.TRUE)) {
+      return callExpr.arguments().stream()
+        .flatMap(TreeUtils.toStreamInstanceOfMapper(RegularArgument.class))
+        .map(RegularArgument::expression)
+        .filter(argExpr -> !isSet(argExpr))
+        .flatMap(this::getNonSerializableExpr);
+    }
+
+    if (serializationFunctions.getOptionalForType(callExpr.callee().typeV2()).isPresent()) {
+      Stream.of();
+    }
+
+    if (nonSerializableTypes.getOptionalForType(callExpr.typeV2()).isPresent() ||
+      NON_SERIALIZABLE_FQNS.contains(fullyQualifiedName) ||
+      isUserDefinedClassWithoutSerializationMethods(calleeSymbol)) {
+      return Stream.of(new IssueLocation(callExpr));
+    }
+    return Stream.of();
+  }
+
+  private static boolean isSerializationMethodCall(CallExpression callExpr) {
+    if (callExpr.callee().is(Tree.Kind.QUALIFIED_EXPR)) {
+      QualifiedExpression qualifiedExpr = (QualifiedExpression) callExpr.callee();
+      String methodName = qualifiedExpr.name().name();
+      return SERIALIZATION_METHOD_NAMES.contains(methodName);
+    }
+    return false;
+  }
+
+  private static boolean isUserDefinedClassWithoutSerializationMethods(Symbol symbol) {
+    return symbol.usages().stream()
+      .filter(usage -> usage.kind() == Usage.Kind.CLASS_DECLARATION)
+      .map(Usage::tree)
+      .findFirst()
+      .flatMap(TreeUtils::getSymbolFromTree)
+      .filter(ClassSymbol.class::isInstance)
+      .map(ClassSymbol.class::cast)
+      .map(classSymbol -> !classSymbol.canHaveMember("__dict__") && !classSymbol.canHaveMember("__json__"))
+      .orElse(false);
+  }
+
+  private Stream<IssueLocation> getNonSerializableInDictionaryLiteral(DictionaryLiteral dictLiteral) {
+    // Check dictionary keys and values recursively
+    return dictLiteral.elements().stream()
+      .flatMap(TreeUtils.toStreamInstanceOfMapper(KeyValuePair.class))
+      .flatMap(kvPair -> Stream.concat(getNonSerializableExpr(kvPair.key()), getNonSerializableExpr(kvPair.value())));
+  }
+
+  private Stream<IssueLocation> getNonSerializableInListLiteral(ListLiteral listLiteral) {
+    return listLiteral.elements().expressions().stream()
+      .flatMap(this::getNonSerializableExpr);
+  }
+
+  private Stream<IssueLocation> getNonSerializableInTuple(Tuple tuple) {
+    return tuple.elements().stream()
+      .flatMap(this::getNonSerializableExpr);
+  }
+
+  private Stream<IssueLocation> getNonSerializableFromName(Name name) {
+    var assignedValue = Expressions.singleAssignedValue(name);
+    if (assignedValue == null) {
+      return getNonSerializableFromFuncDef(name);
+    }
+    return getNonSerializableExpr(assignedValue)
+      .map(assignedValueLocation -> new IssueLocation(name, Optional.of(assignedValueLocation.mainLocation)));
+  }
+
+  private static Stream<IssueLocation> getNonSerializableFromFuncDef(Name name) {
+    return TreeUtils.getSymbolFromTree(name).stream()
+      .flatMap(symbol -> symbol.usages().stream())
+      .filter(usage -> usage.kind() == Usage.Kind.FUNC_DECLARATION)
+      .findFirst()
+      .map(usage -> new IssueLocation(name)).stream();
+  }
+
+  private boolean isSet(Expression expr) {
+    return setType.check(expr.typeV2()) == TriBool.TRUE;
+  }
+
+  private Stream<IssueLocation> getNonSerializableFromTypeOrFqn(Expression expr) {
+    if (nonSerializableTypes.getOptionalForType(expr.typeV2()).isPresent()) {
+      return Stream.of(new IssueLocation(expr));
+    }
+
+    return TreeUtils.getSymbolFromTree(expr)
+      .map(Symbol::fullyQualifiedName)
+      .filter(NON_SERIALIZABLE_FQNS::contains)
+      .map(fqn -> new IssueLocation(expr)).stream();
+  }
+}
diff --git a/python-checks/src/main/java/org/sonar/python/checks/OpenSourceCheckList.java b/python-checks/src/main/java/org/sonar/python/checks/OpenSourceCheckList.java
@@ -130,6 +130,7 @@ public Stream<Class<?>> getChecks() {
       AsyncWithContextManagerCheck.class,
       AwsLambdaCrossCallCheck.class,
       AWSLambdaReservedEnvironmentVariableCheck.class,
+      AwsLambdaReturnValueAreSerializableCheck.class,
       BackslashInStringCheck.class,
       BackticksUsageCheck.class,
       BareRaiseInFinallyCheck.class,
diff --git a/python-checks/src/main/java/org/sonar/python/checks/utils/AwsLambdaChecksUtils.java b/python-checks/src/main/java/org/sonar/python/checks/utils/AwsLambdaChecksUtils.java
@@ -47,9 +47,9 @@ public static boolean isOnlyLambdaHandler(SubscriptionContext ctx, FunctionDef f
 
   private static boolean isLambdaHandlerFqn(ProjectConfiguration projectConfiguration, String fqn) {
     return projectConfiguration.awsProjectConfiguration()
-             .awsLambdaHandlers()
-             .stream()
-             .anyMatch(handler -> handler.fullyQualifiedName().equals(fqn));
+      .awsLambdaHandlers()
+      .stream()
+      .anyMatch(handler -> handler.fullyQualifiedName().equals(fqn));
   }
 
   private static boolean isFqnCalledFromLambdaHandler(CallGraph callGraph, ProjectConfiguration projectConfiguration, String fqn) {
diff --git a/python-checks/src/main/resources/org/sonar/l10n/py/rules/python/S7613.html b/python-checks/src/main/resources/org/sonar/l10n/py/rules/python/S7613.html
@@ -0,0 +1,71 @@
+<p>This rule raises an issue when AWS Lambda handlers return values that are not JSON serializable.</p>
+<h2>Why is this an issue?</h2>
+<p>For synchronous AWS Lambda invocations, like via API Gateway or direct SDK calls, the value returned by the handler is automatically serialized
+into a JSON string before being sent back in the response. If the return value contains objects that are not native JSON types like
+<code>datetime</code> objects, sets, or custom class instances, the serialization will fail, causing a <code>TypeError</code>. This will prevent the
+Lambda from returning a valid response to the client.</p>
+<h2>How to fix it</h2>
+<p>Convert non-JSON-serializable objects to their string representation or to JSON-serializable types before returning them:</p>
+<ul>
+  <li> For <code>datetime</code> objects: Convert to ISO format strings using <code>.isoformat()</code> </li>
+  <li> For sets: Convert to lists using <code>list(set_object)</code> </li>
+  <li> For custom objects: convert them to dictionaries using the <code>__dict__</code> field, <code>dataclasses.asdict(…​)</code> for dataclasses or
+  a custom <code>todict()</code> method. </li>
+</ul>
+<p>See the following examples for more details on how to handle custom classes:</p>
+<pre>
+import json
+import dataclasses
+
+# A custom class representing a user
+@dataclasses.dataclass
+class User:
+    name: str
+    age: int
+
+    def to_dict(self) -&gt; dict:
+        return { "name": self.name, "age": self.age }
+
+user = User("Alice", 30)
+
+# Method 1: Using __dict__ field
+json.dumps(user.__dict__)
+
+# Method 2: Using dataclasses.asdict()
+json.dumps(dataclasses.asdict(user))
+
+# Method 3: Using custom to_dict() method
+json.dumps(user.to_dict())
+</pre>
+<h3>Code examples</h3>
+<h4>Noncompliant code example</h4>
+<pre data-diff-id="1" data-diff-type="noncompliant">
+import datetime
+
+def lambda_handler(event, context):
+    return {
+        "message": "Request processed successfully",
+        "timestamp": datetime.datetime.now()  # Noncompliant: not JSON serializable
+    }
+</pre>
+<h4>Compliant solution</h4>
+<pre data-diff-id="1" data-diff-type="compliant">
+import datetime
+
+def lambda_handler(event, context):
+    return {
+        "message": "Request processed successfully",
+        "timestamp": datetime.datetime.now().isoformat()  # Compliant: converted to string
+    }
+</pre>
+<h2>Resources</h2>
+<h3>Documentation</h3>
+<ul>
+  <li> AWS Documentation - <a href="https://docs.aws.amazon.com/lambda/latest/dg/python-handler.html#python-handler-return">Define Lambda function
+  handler in Python </a> </li>
+  <li> Python Documentation - <a href="https://docs.python.org/3/library/json.html">json — JSON encoder and decoder</a> </li>
+  <li> Python Documentation - <a href="https://docs.python.org/3/reference/datamodel.html#object.<em>dict</em>">object.__dict__ field</a> </li>
+  <li> Python Documentation - <a href="https://docs.python.org/3/library/datetime.html#datetime.date.isoformat">datetime.date.isoformat()</a> </li>
+  <li> Python Documentation - <a href="https://docs.python.org/3/library/dataclasses.html#dataclasses.asdict">dateclasses.asdict()</a> </li>
+</ul>
+
diff --git a/python-checks/src/main/resources/org/sonar/l10n/py/rules/python/S7613.json b/python-checks/src/main/resources/org/sonar/l10n/py/rules/python/S7613.json
@@ -0,0 +1,22 @@
+{
+  "title": "AWS Lambda handlers should return only JSON serializable values",
+  "type": "BUG",
+  "status": "ready",
+  "remediation": {
+    "func": "Constant\/Issue",
+    "constantCost": "5min"
+  },
+  "tags": [],
+  "defaultSeverity": "Major",
+  "ruleSpecification": "RSPEC-7613",
+  "sqKey": "S7613",
+  "scope": "All",
+  "quickfix": "infeasible",
+  "code": {
+    "impacts": {
+      "MAINTAINABILITY": "LOW",
+      "RELIABILITY": "HIGH"
+    },
+    "attribute": "CONVENTIONAL"
+  }
+}
diff --git a/python-checks/src/main/resources/org/sonar/l10n/py/rules/python/Sonar_way_profile.json b/python-checks/src/main/resources/org/sonar/l10n/py/rules/python/Sonar_way_profile.json
@@ -290,6 +290,7 @@
     "S7517",
     "S7519",
     "S7617",
+    "S7613",
     "S7632"
   ]
 }
diff --git a/python-checks/src/test/java/org/sonar/python/checks/AwsLambdaReturnValueAreSerializableCheckTest.java b/python-checks/src/test/java/org/sonar/python/checks/AwsLambdaReturnValueAreSerializableCheckTest.java
diff --git a/python-checks/src/test/resources/checks/awslambdaReturnValueAreSerializable.py b/python-checks/src/test/resources/checks/awslambdaReturnValueAreSerializable.py

Original file line number	Diff line number	Diff line change
`@@ -290,6 +290,7 @@`
`290`	`290`	`"S7517",`
`291`	`291`	`"S7519",`
`292`	`292`	`"S7617",`
	`293`	`+ "S7613",`
`293`	`294`	`"S7632"`
`294`	`295`	`]`
`295`	`296`	`}`