feat: support assigning a user to issues via --assign-user and updating custom tags via --custom-tags in fcli fpr issue audit

Author: SangameshV

fcli-core/fcli-aviator-common/src/main/java/com/fortify/cli/aviator/fpr/model/AuditIssue.java

@@ -32,6 +32,7 @@ public class AuditIssue {
     @Builder.Default private Map<String, String> tags = new HashMap<>();
     @Builder.Default private List<Comment> threadedComments = new ArrayList<>();
     @Builder.Default private List<TagHistoryEntry> tagHistory = new ArrayList<>();
+    private String assignedUser;
 
     public void addTag(String tagId, String tagValue) {
         if (tagId != null) {

fcli-core/fcli-aviator-common/src/main/java/com/fortify/cli/aviator/fpr/processor/AuditProcessor.java

@@ -185,6 +185,9 @@ private AuditIssue processAuditIssue(Element issueElement) {
         AuditIssue.AuditIssueBuilder auditIssueBuilder = AuditIssue.builder();
 
         auditIssueBuilder.instanceId(issueElement.getAttribute("instanceId"));
+        if (issueElement.hasAttribute("assignedUser")) {
+            auditIssueBuilder.assignedUser(issueElement.getAttribute("assignedUser"));
+        }
         auditIssueBuilder.suppressed(Boolean.parseBoolean(issueElement.getAttribute("suppressed")));
 
         String revisionStr = issueElement.getAttribute("revision");
@@ -281,21 +284,64 @@ public void updateIssueTag(AuditIssue auditIssue, String tagId, String tagValue)
      */
     public boolean auditIssue(String instanceId, String tagId, String tagValue,
                               String comment, String username, boolean suppress) {
+        return auditIssueMulti(instanceId, java.util.Map.of(tagId, tagValue), comment, username, suppress, null);
+    }
+
+    /**
+     * Backwards-compatible overload without an assigned user.
+     */
+    public boolean auditIssueMulti(String instanceId, java.util.Map<String, String> tagIdToValue,
+                                   String comment, String username, boolean suppress) {
+        return auditIssueMulti(instanceId, tagIdToValue, comment, username, suppress, null);
+    }
+
+    /**
+     * Audits a single issue, applying multiple tag changes atomically: bumps revision once,
+     * writes only the tags whose value actually changes (and a TagHistory entry for each),
+     * appends an optional comment once, optionally suppresses the issue, and optionally
+     * assigns the issue to a user (stored as the {@code assignedUser} attribute on the
+     * {@code <Issue>} element). Returns true if anything changed, false if the call was a no-op.
+     */
+    public boolean auditIssueMulti(String instanceId, java.util.Map<String, String> tagIdToValue,
+                                   String comment, String username, boolean suppress,
+                                   String assignedUser) {
         if (username == null || username.isBlank()) {
             throw new IllegalArgumentException("username must be provided");
         }
+        if (tagIdToValue == null) { tagIdToValue = java.util.Map.of(); }
+
         Element issueElement = findIssueElement(instanceId);
         boolean issueCreated = false;
         if (issueElement == null) {
             issueElement = createSimpleIssueElement(instanceId);
             issueCreated = true;
         }
-        String currentTagValue = getCurrentTagValue(issueElement, tagId);
-        boolean tagChanged = !java.util.Objects.equals(tagValue, currentTagValue);
+
+        java.util.Map<String, String> changedTags = new java.util.LinkedHashMap<>();
+        for (var entry : tagIdToValue.entrySet()) {
+            String tagId = entry.getKey();
+            String tagValue = entry.getValue();
+            if (tagId == null || tagId.isBlank() || tagValue == null) { continue; }
+            String currentTagValue = getCurrentTagValue(issueElement, tagId);
+            if (!java.util.Objects.equals(tagValue, currentTagValue)) {
+                changedTags.put(tagId, tagValue);
+            }
+        }
+
         boolean suppressChanged = suppress && !"true".equalsIgnoreCase(issueElement.getAttribute("suppressed"));
         boolean commentAdded = comment != null && !comment.isBlank();
 
-        if (!tagChanged && !suppressChanged && !commentAdded) {
+        boolean assignChanged = false;
+        if (assignedUser != null) {
+            String currentAssigned = issueElement.hasAttribute("assignedUser")
+                    ? issueElement.getAttribute("assignedUser") : "";
+            // Empty string clears the assignment.
+            if (!assignedUser.equals(currentAssigned)) {
+                assignChanged = true;
+            }
+        }
+
+        if (changedTags.isEmpty() && !suppressChanged && !commentAdded && !assignChanged) {
             return false;
         }
 
@@ -305,18 +351,27 @@ public boolean auditIssue(String instanceId, String tagId, String tagValue,
                 .orElse(0);
         issueElement.setAttribute("revision", String.valueOf(revision + 1));
 
-        if (tagChanged) {
-            updateOrAddTag(issueElement, tagId, tagValue);
+        if (!changedTags.isEmpty()) {
             Element clientAuditTrail = getClientAuditTrailElement(issueElement);
-            addTagHistory(clientAuditTrail, tagId, tagValue, username);
+            for (var ct : changedTags.entrySet()) {
+                updateOrAddTag(issueElement, ct.getKey(), ct.getValue());
+                addTagHistory(clientAuditTrail, ct.getKey(), ct.getValue(), username);
+            }
         }
         if (commentAdded) {
             addCommentToIssueElement(issueElement, comment, username);
         }
         if (suppressChanged) {
             issueElement.setAttribute("suppressed", "true");
         }
-        return tagChanged || suppressChanged || commentAdded || issueCreated;
+        if (assignChanged) {
+            if (assignedUser.isEmpty()) {
+                issueElement.removeAttribute("assignedUser");
+            } else {
+                issueElement.setAttribute("assignedUser", assignedUser);
+            }
+        }
+        return !changedTags.isEmpty() || suppressChanged || commentAdded || assignChanged || issueCreated;
     }
 
     private String getCurrentTagValue(Element issueElement, String tagId) {

fcli-core/fcli-fpr/src/main/java/com/fortify/cli/fpr/_common/helper/FPRHelper.java

@@ -20,8 +20,12 @@
 import com.fasterxml.jackson.databind.node.ObjectNode;
 import com.fortify.cli.aviator.fpr.FPRProcessor;
 import com.fortify.cli.aviator.fpr.Vulnerability;
+import com.fortify.cli.aviator.fpr.filter.FilterTemplate;
+import com.fortify.cli.aviator.fpr.filter.TagDefinition;
+import com.fortify.cli.aviator.fpr.filter.TagValue;
 import com.fortify.cli.aviator.fpr.model.AuditIssue;
 import com.fortify.cli.aviator.fpr.processor.AuditProcessor;
+import com.fortify.cli.aviator.fpr.processor.FilterTemplateParser;
 import com.fortify.cli.aviator.fpr.processor.StreamingFVDLProcessor;
 import com.fortify.cli.aviator.util.FprHandle;
 
@@ -186,6 +190,9 @@ public static void embedAuditHistory(ObjectNode node, AuditIssue auditIssue) {
         if (auditIssue == null) { return; }
 
         node.put("revision", auditIssue.getRevision());
+        if (auditIssue.getAssignedUser() != null && !auditIssue.getAssignedUser().isBlank()) {
+            node.put("assignedUser", auditIssue.getAssignedUser());
+        }
 
         if (!auditIssue.getTags().isEmpty()) {
             var tagsNode = MAPPER.createObjectNode();
@@ -220,4 +227,58 @@ public static void embedAuditHistory(ObjectNode node, AuditIssue auditIssue) {
             node.set("tagHistory", historyArray);
         }
     }
-}
+    /**
+     * Loads the FPR's filter template (if present), exposing tag definitions
+     * for resolving custom-tag names and their valid values. Returns an empty
+     * Optional if the FPR has no filtertemplate.xml.
+     */
+    public static java.util.Optional<FilterTemplate> loadFilterTemplate(FprHandle fprHandle) {
+        var auditProcessor = new com.fortify.cli.aviator.fpr.processor.AuditProcessor(fprHandle);
+        auditProcessor.processAuditXML();
+        return new FilterTemplateParser(fprHandle, auditProcessor).parseFilterTemplate();
+    }
+
+    /**
+     * Resolves a user-supplied tag name (or GUID) and value to the canonical
+     * tagId / tagValue pair for use with AuditProcessor. Tag and value lookups
+     * are case-insensitive. If the tag is not found in the filter template,
+     * the input is treated as a raw GUID. If the value is not in the tag's
+     * defined values and the tag is not extensible, throws IllegalArgumentException.
+     */
+    public static java.util.Map.Entry<String, String> resolveCustomTag(
+            FilterTemplate filterTemplate, String tagNameOrId, String value) {
+        if (tagNameOrId == null || tagNameOrId.isBlank()) {
+            throw new IllegalArgumentException("Tag name/id must not be blank");
+        }
+        if (value == null) {
+            throw new IllegalArgumentException("Tag value must not be null for tag '" + tagNameOrId + "'");
+        }
+        if (filterTemplate == null || filterTemplate.getTagDefinitions() == null) {
+            return java.util.Map.entry(tagNameOrId, value);
+        }
+        TagDefinition match = null;
+        for (var def : filterTemplate.getTagDefinitions()) {
+            if (tagNameOrId.equalsIgnoreCase(def.getName()) || tagNameOrId.equalsIgnoreCase(def.getId())) {
+                match = def;
+                break;
+            }
+        }
+        if (match == null) {
+            return java.util.Map.entry(tagNameOrId, value);
+        }
+        if (match.getValues() != null) {
+            for (TagValue tv : match.getValues()) {
+                if (tv.getValue() != null && tv.getValue().equalsIgnoreCase(value)) {
+                    return java.util.Map.entry(match.getId(), tv.getValue());
+                }
+            }
+        }
+        if (!match.isExtensible()) {
+            var allowed = match.getValues() == null ? java.util.List.<String>of()
+                    : match.getValues().stream().map(TagValue::getValue).toList();
+            throw new IllegalArgumentException("Invalid value '" + value + "' for tag '"
+                    + match.getName() + "'; valid values: " + String.join(", ", allowed));
+        }
+        return java.util.Map.entry(match.getId(), value);
+    }
+}

fcli-core/fcli-fpr/src/main/java/com/fortify/cli/fpr/issue/cli/cmd/FPRIssueAuditCommand.java

@@ -21,6 +21,7 @@
 
 import com.fasterxml.jackson.databind.ObjectMapper;
 import com.fasterxml.jackson.databind.node.ObjectNode;
+import com.fortify.cli.aviator.fpr.filter.FilterTemplate;
 import com.fortify.cli.aviator.fpr.processor.AuditProcessor;
 import com.fortify.cli.aviator.util.Constants;
 import com.fortify.cli.common.exception.FcliSimpleException;
@@ -32,6 +33,7 @@
 import com.fortify.cli.common.util.DisableTest;
 import com.fortify.cli.common.util.DisableTest.TestType;
 import com.fortify.cli.fpr._common.cli.mixin.FPRFileMixin;
+import com.fortify.cli.fpr._common.helper.FPRHelper;
 
 import lombok.Getter;
 import picocli.CommandLine.Command;
@@ -64,20 +66,28 @@ public class FPRIssueAuditCommand extends AbstractOutputCommand {
     @Option(names = {"--instance-ids"}, required = true, split = ",", order = 2)
     private List<String> instanceIds;
 
-    @Option(names = {"--analysis"}, required = true, order = 3)
+    @Option(names = {"--analysis"}, order = 3)
     private String analysis;
 
-    @Option(names = {"--comment"}, order = 4)
+    @DisableTest(TestType.MULTI_OPT_PLURAL_NAME)
+    @Option(names = {"--custom-tags", "-t"}, split = ",", paramLabel = "TAG=VALUE", order = 4)
+    private Map<String, String> customTags;
+
+    @Option(names = {"--comment"}, order = 5)
     private String comment;
 
-    @Option(names = {"--suppress"}, order = 5)
+    @Option(names = {"--suppress"}, order = 6)
     private boolean suppress;
 
-    @Option(names = {"--user"}, order = 6)
+    @Option(names = {"--user"}, order = 7)
     private String user;
 
+    @Option(names = {"--assign-user"}, order = 8)
+    private String assignUser;
+
     @Override
     protected IObjectNodeProducer getObjectNodeProducer() {
+        validateAtLeastOneAction();
         var canonicalAnalysis = validateAnalysis(analysis);
         var username = resolveUsername();
         var uniqueIds = dedupePreservingOrder(instanceIds);
@@ -91,14 +101,18 @@ private List<ObjectNode> applyAudits(List<String> ids, String canonicalAnalysis,
         try (var fprHandle = fprFileMixin.createFprHandle()) {
             var auditProcessor = new AuditProcessor(fprHandle);
             auditProcessor.processAuditXML();
+
+            // Resolve all custom-tag inputs to canonical (tagId, tagValue) pairs once.
+            Map<String, String> resolvedTags = resolveTagsForFpr(fprHandle, canonicalAnalysis);
+
             var results = new ArrayList<ObjectNode>(ids.size());
             boolean anyChanged = false;
             for (var id : ids) {
-                boolean changed = auditProcessor.auditIssue(id, Constants.ANALYSIS_TAG_ID,
-                        canonicalAnalysis, comment, username, suppress);
+                boolean changed = auditProcessor.auditIssueMulti(id, resolvedTags, comment, username, suppress, assignUser);
                 anyChanged |= changed;
-                results.add(buildResultRow(id, canonicalAnalysis, username, changed));
+                results.add(buildResultRow(id, canonicalAnalysis, resolvedTags, username, changed));
             }
+            // (assignedUser already included by buildResultRow when set)
             if (anyChanged) {
                 auditProcessor.saveAuditXml();
             }
@@ -108,17 +122,62 @@ private List<ObjectNode> applyAudits(List<String> ids, String canonicalAnalysis,
         }
     }
 
-    private ObjectNode buildResultRow(String id, String canonicalAnalysis, String username, boolean changed) {
+    private Map<String, String> resolveTagsForFpr(com.fortify.cli.aviator.util.FprHandle fprHandle,
+                                                  String canonicalAnalysis) {
+        var tags = new LinkedHashMap<String, String>();
+        if (canonicalAnalysis != null) {
+            tags.put(Constants.ANALYSIS_TAG_ID, canonicalAnalysis);
+        }
+        if (customTags == null || customTags.isEmpty()) {
+            return tags;
+        }
+        FilterTemplate filterTemplate = FPRHelper.loadFilterTemplate(fprHandle).orElse(null);
+        for (var entry : customTags.entrySet()) {
+            try {
+                var resolved = FPRHelper.resolveCustomTag(filterTemplate, entry.getKey(), entry.getValue());
+                tags.put(resolved.getKey(), resolved.getValue());
+            } catch (IllegalArgumentException e) {
+                throw new FcliSimpleException(e.getMessage());
+            }
+        }
+        return tags;
+    }
+
+    private ObjectNode buildResultRow(String id, String canonicalAnalysis, Map<String, String> resolvedTags,
+                                      String username, boolean changed) {
         var row = MAPPER.createObjectNode();
         row.put("instanceId", id);
-        row.put("analysis", canonicalAnalysis);
+        row.put("analysis", canonicalAnalysis != null ? canonicalAnalysis : "");
+        if (customTags != null && !customTags.isEmpty()) {
+            var tagsNode = MAPPER.createObjectNode();
+            for (var entry : resolvedTags.entrySet()) {
+                if (!Constants.ANALYSIS_TAG_ID.equals(entry.getKey())) {
+                    tagsNode.put(entry.getKey(), entry.getValue());
+                }
+            }
+            row.set("customTags", tagsNode);
+        }
         row.put("comment", comment != null ? comment : "");
         row.put("suppressed", suppress);
+        if (assignUser != null) {
+            row.put("assignedUser", assignUser);
+        }
         row.put("user", username);
         row.put("__action__", changed ? "AUDITED" : "UNCHANGED");
         return row;
     }
 
+    private void validateAtLeastOneAction() {
+        boolean hasAnalysis = analysis != null && !analysis.isBlank();
+        boolean hasTags = customTags != null && !customTags.isEmpty();
+        boolean hasComment = comment != null && !comment.isBlank();
+        boolean hasAssign = assignUser != null;
+        if (!hasAnalysis && !hasTags && !hasComment && !suppress && !hasAssign) {
+            throw new FcliSimpleException(
+                    "At least one of --analysis, --custom-tags, --comment, --suppress, or --assign-user must be provided");
+        }
+    }
+
     private static List<String> dedupePreservingOrder(List<String> ids) {
         var seen = new LinkedHashSet<String>();
         for (var id : ids) {
@@ -133,7 +192,7 @@ private static List<String> dedupePreservingOrder(List<String> ids) {
     }
 
     private String validateAnalysis(String value) {
-        if (value == null) { return null; }
+        if (value == null || value.isBlank()) { return null; }
         var canonical = VALID_ANALYSIS_VALUES.get(value.toLowerCase());
         if (canonical == null) {
             throw new FcliSimpleException("Invalid --analysis value '" + value

fcli-core/fcli-fpr/src/main/resources/com/fortify/cli/fpr/i18n/FPRMessages.properties

@@ -22,16 +22,18 @@ fcli.fpr.issue.get.embed = Comma-separated list of extra data to embed. Valid va
 fcli.fpr.issue.count.fpr = Path to the local FPR file to read.
 fcli.fpr.issue.audit.fpr = Path to the local FPR file to audit.
 fcli.fpr.issue.audit.instance-ids = Comma-separated list of one or more issue instanceIds to audit.
-fcli.fpr.issue.audit.analysis = The analysis value to set. Valid values (case-insensitive): 'Not an Issue', 'Exploitable', 'Suspicious', 'Reliability Issue', 'False Positive', 'Bad Practice'.
+fcli.fpr.issue.audit.analysis = Optional analysis value to set. Valid values (case-insensitive): 'Not an Issue', 'Exploitable', 'Suspicious', 'Reliability Issue', 'False Positive', 'Bad Practice'.
+fcli.fpr.issue.audit.custom-tags = Comma-separated TAG=VALUE pairs for custom tags. TAG can be the tag name or its GUID; lookups are case-insensitive. Example: "--custom-tags 'Auditor Status=Reviewed,Severity=High'".
 fcli.fpr.issue.audit.comment = Optional comment to add to the issue audit trail.
 fcli.fpr.issue.audit.suppress = Suppress the issue in the FPR file.
 fcli.fpr.issue.audit.user = Username to record in the audit trail. Defaults to the current operating system user.
+fcli.fpr.issue.audit.assign-user = Assign the issue to the specified user. Stored as the assignedUser attribute on the Issue element. Pass an empty string to clear the assignment.
 fcli.fpr.remediation.apply-remediations.fpr = Path to the local FPR file containing remediations.
 fcli.fpr.remediation.apply-remediations.source-root = Root directory of the source code to apply remediations to.
 
 # Default output columns
 fcli.fpr.issue.list.output.table.args = instanceId,category,priority,analyzerName,primaryFile,primaryLine,audited,suppressed
 fcli.fpr.issue.get.output.table.args = instanceId,category,kingdom,type,subtype,analyzerName,priority,primaryFile,primaryLine,audited,suppressed,issueStatus,shortDescription
 fcli.fpr.issue.count.output.table.args = category,total,audited,suppressed
-fcli.fpr.issue.audit.output.table.args = instanceId,analysis,comment,suppressed,user,__action__
+fcli.fpr.issue.audit.output.table.args = instanceId,analysis,customTags,comment,suppressed,assignedUser,user,__action__
 fcli.fpr.remediation.apply-remediations.output.table.args = totalRemediations,appliedRemediations,skippedRemediations,__action__