diff --git a/src/main/java/de/rub/nds/scanner/core/report/AnalyzedPropertyTextEncoder.java b/src/main/java/de/rub/nds/scanner/core/report/AnalyzedPropertyTextEncoder.java index 22b275d..c42faf0 100644 --- a/src/main/java/de/rub/nds/scanner/core/report/AnalyzedPropertyTextEncoder.java +++ b/src/main/java/de/rub/nds/scanner/core/report/AnalyzedPropertyTextEncoder.java @@ -11,14 +11,30 @@ import de.rub.nds.scanner.core.probe.AnalyzedProperty; import java.util.HashMap; +/** + * An encoder that converts AnalyzedProperty instances to their text representation. Uses a provided + * mapping to translate properties to custom strings. + */ public class AnalyzedPropertyTextEncoder extends Encoder { private final HashMap map; + /** + * Creates a new AnalyzedPropertyTextEncoder with the specified property-to-text mapping. + * + * @param map a HashMap mapping AnalyzedProperty instances to their string representations + */ public AnalyzedPropertyTextEncoder(HashMap map) { this.map = map; } + /** + * Encodes an AnalyzedProperty to its string representation. If a mapping exists, returns the + * mapped value; otherwise returns the property's name. + * + * @param analyzedProperty the property to encode + * @return the string representation of the property + */ @Override public String encode(AnalyzedProperty analyzedProperty) { if (map == null) { diff --git a/src/main/java/de/rub/nds/scanner/core/report/AnsiColor.java b/src/main/java/de/rub/nds/scanner/core/report/AnsiColor.java index 35397d8..c103686 100644 --- a/src/main/java/de/rub/nds/scanner/core/report/AnsiColor.java +++ b/src/main/java/de/rub/nds/scanner/core/report/AnsiColor.java @@ -11,6 +11,10 @@ import java.util.HashMap; import java.util.Map; +/** + * Enum representing ANSI color codes for terminal output. Provides foreground colors, background + * colors, and text formatting options. + */ public enum AnsiColor { RESET("\u001B[0m"), BLACK("\u001B[30m"), @@ -48,10 +52,21 @@ public enum AnsiColor { } } + /** + * Returns the AnsiColor corresponding to the given ANSI code string. + * + * @param code the ANSI code string + * @return the corresponding AnsiColor, or null if no match is found + */ public static AnsiColor getAnsiColor(String code) { return MAP.get(code); } + /** + * Returns the ANSI code string for this color. + * + * @return the ANSI code string + */ public String getCode() { return code; } diff --git a/src/main/java/de/rub/nds/scanner/core/report/AnsiEscapeSequence.java b/src/main/java/de/rub/nds/scanner/core/report/AnsiEscapeSequence.java index 8c0be2e..9223471 100644 --- a/src/main/java/de/rub/nds/scanner/core/report/AnsiEscapeSequence.java +++ b/src/main/java/de/rub/nds/scanner/core/report/AnsiEscapeSequence.java @@ -8,8 +8,15 @@ */ package de.rub.nds.scanner.core.report; +/** + * Utility class containing ANSI escape sequences for terminal manipulation. Provides constants for + * cursor movement and line manipulation. + */ public class AnsiEscapeSequence { + /** ANSI escape sequence to move cursor up one line */ public static final String ANSI_ONE_LINE_UP = "\033[1A"; + + /** ANSI escape sequence to erase the current line */ public static final String ANSI_ERASE_LINE = "\033[2K"; } diff --git a/src/main/java/de/rub/nds/scanner/core/report/ColorEncoding.java b/src/main/java/de/rub/nds/scanner/core/report/ColorEncoding.java index 056d148..1edd3a5 100644 --- a/src/main/java/de/rub/nds/scanner/core/report/ColorEncoding.java +++ b/src/main/java/de/rub/nds/scanner/core/report/ColorEncoding.java @@ -11,18 +11,41 @@ import de.rub.nds.scanner.core.probe.result.TestResult; import java.util.HashMap; +/** + * Handles color encoding for test results in terminal output. Maps test results to ANSI colors for + * visual differentiation. + */ public class ColorEncoding { private final HashMap colorMap; + /** + * Creates a new ColorEncoding with the specified result-to-color mapping. + * + * @param colorMap a HashMap mapping TestResult instances to AnsiColor codes + */ public ColorEncoding(HashMap colorMap) { this.colorMap = colorMap; } + /** + * Returns the AnsiColor associated with a given test result. + * + * @param result the test result + * @return the associated AnsiColor, or null if no mapping exists + */ public AnsiColor getColor(TestResult result) { return colorMap.get(result); } + /** + * Encodes the given text with the color associated with the test result. If a color mapping + * exists and is not DEFAULT_COLOR, wraps the text with appropriate ANSI codes. + * + * @param result the test result determining the color + * @param encodedText the text to be colored + * @return the color-encoded text string + */ public String encode(TestResult result, String encodedText) { AnsiColor color = this.getColor(result); if (color != null && color != AnsiColor.DEFAULT_COLOR) { diff --git a/src/main/java/de/rub/nds/scanner/core/report/Encoder.java b/src/main/java/de/rub/nds/scanner/core/report/Encoder.java index aacdf1e..8d3727c 100644 --- a/src/main/java/de/rub/nds/scanner/core/report/Encoder.java +++ b/src/main/java/de/rub/nds/scanner/core/report/Encoder.java @@ -8,7 +8,18 @@ */ package de.rub.nds.scanner.core.report; +/** + * Abstract base class for encoding objects to their string representation. + * + * @param the type of objects this encoder can encode + */ public abstract class Encoder { + /** + * Encodes the given object to its string representation. + * + * @param t the object to encode + * @return the string representation of the object + */ public abstract String encode(T t); } diff --git a/src/main/java/de/rub/nds/scanner/core/report/PerformanceData.java b/src/main/java/de/rub/nds/scanner/core/report/PerformanceData.java index 17c8aa4..798db37 100644 --- a/src/main/java/de/rub/nds/scanner/core/report/PerformanceData.java +++ b/src/main/java/de/rub/nds/scanner/core/report/PerformanceData.java @@ -10,6 +10,10 @@ import de.rub.nds.scanner.core.probe.ProbeType; +/** + * Container for performance data of a single probe execution. Tracks timing information for + * performance analysis. + */ public class PerformanceData { private ProbeType type; @@ -24,32 +28,69 @@ private PerformanceData() { this.stopTime = 0; } + /** + * Creates a new PerformanceData instance with the specified parameters. + * + * @param type the type of probe + * @param startTime the start time in milliseconds + * @param stopTime the stop time in milliseconds + */ public PerformanceData(ProbeType type, long startTime, long stopTime) { this.type = type; this.startTime = startTime; this.stopTime = stopTime; } + /** + * Returns the probe type. + * + * @return the probe type + */ public ProbeType getType() { return type; } + /** + * Sets the probe type. + * + * @param type the probe type to set + */ public void setType(ProbeType type) { this.type = type; } + /** + * Returns the start time in milliseconds. + * + * @return the start time + */ public long getStartTime() { return startTime; } + /** + * Sets the start time in milliseconds. + * + * @param startTime the start time to set + */ public void setStartTime(long startTime) { this.startTime = startTime; } + /** + * Returns the stop time in milliseconds. + * + * @return the stop time + */ public long getStopTime() { return stopTime; } + /** + * Sets the stop time in milliseconds. + * + * @param stopTime the stop time to set + */ public void setStopTime(long stopTime) { this.stopTime = stopTime; } diff --git a/src/main/java/de/rub/nds/scanner/core/report/PrintingScheme.java b/src/main/java/de/rub/nds/scanner/core/report/PrintingScheme.java index 05a8432..aa8950d 100644 --- a/src/main/java/de/rub/nds/scanner/core/report/PrintingScheme.java +++ b/src/main/java/de/rub/nds/scanner/core/report/PrintingScheme.java @@ -13,6 +13,10 @@ import de.rub.nds.scanner.core.probe.result.TestResult; import java.util.HashMap; +/** + * Defines the visual presentation scheme for scan report results, including text encoding and color + * encoding configurations for different property types and categories. + */ public class PrintingScheme { private HashMap valueColorEncodings; @@ -27,8 +31,19 @@ public class PrintingScheme { private ColorEncoding defaultColorEncoding; + /** Constructs a new PrintingScheme with default settings. */ public PrintingScheme() {} + /** + * Constructs a new PrintingScheme with specified encoding configurations. + * + * @param colorEncodings property-specific color encodings + * @param textEncodings category-specific text encodings + * @param defaultTextEncoding default text encoder for values without specific encodings + * @param defaultColorEncoding default color encoder for values without specific encodings + * @param specialTextEncoding property-specific text encodings that override category encodings + * @param keyTextEncoding encoders for property keys/names + */ public PrintingScheme( HashMap colorEncodings, HashMap textEncodings, @@ -44,14 +59,32 @@ public PrintingScheme( this.keyTextEncoding = keyTextEncoding; } + /** + * Returns the map of property-specific color encodings. + * + * @return map of color encodings for specific properties + */ public HashMap getValueColorEncodings() { return valueColorEncodings; } + /** + * Returns the map of category-specific text encodings. + * + * @return map of text encodings for property categories + */ public HashMap getValueTextEncodings() { return valueTextEncodings; } + /** + * Encodes the result value for a property as a string with optional color formatting. + * + * @param report the scan report containing the result + * @param property the property whose result should be encoded + * @param useColors whether to apply color encoding to the result + * @return the encoded string representation of the result + */ public String getEncodedString( ScanReport report, AnalyzedProperty property, boolean useColors) { TestResult result = report.getResult(property); @@ -70,6 +103,13 @@ public String getEncodedString( } } + /** + * Encodes the result value for a property as plain text without color formatting. + * + * @param report the scan report containing the result + * @param property the property whose result should be encoded + * @return the plain text representation of the result + */ public String getEncodedValueText(ScanReport report, AnalyzedProperty property) { TestResult result = report.getResult(property); TestResultTextEncoder textEncoding = specialValueTextEncoding.get(property); @@ -80,6 +120,13 @@ public String getEncodedValueText(ScanReport report, AnalyzedProperty property) return textEncoding.encode(result); } + /** + * Encodes the property key/name as text. + * + * @param report the scan report (currently unused but kept for API consistency) + * @param property the property whose key should be encoded + * @return the encoded text representation of the property key + */ public String getEncodedKeyText(ScanReport report, AnalyzedProperty property) { Encoder textEncoding = keyTextEncoding.getOrDefault(property, new AnalyzedPropertyTextEncoder(null)); @@ -87,6 +134,13 @@ public String getEncodedKeyText(ScanReport report, AnalyzedProperty property) { return textEncoding.encode(property); } + /** + * Determines the appropriate color for displaying a property's result value. + * + * @param report the scan report containing the result + * @param property the property whose result color should be determined + * @return the ANSI color to use for the result value + */ public AnsiColor getValueColor(ScanReport report, AnalyzedProperty property) { TestResult result = report.getResult(property); ColorEncoding colorEncoding = @@ -94,6 +148,14 @@ public AnsiColor getValueColor(ScanReport report, AnalyzedProperty property) { return colorEncoding.getColor(result); } + /** + * Determines the color for displaying a property key. Currently always returns the default + * color. + * + * @param report the scan report (currently unused) + * @param property the property (currently unused) + * @return the default ANSI color + */ public AnsiColor getKeyColor(ScanReport report, AnalyzedProperty property) { return AnsiColor.DEFAULT_COLOR; } diff --git a/src/main/java/de/rub/nds/scanner/core/report/ReportCreator.java b/src/main/java/de/rub/nds/scanner/core/report/ReportCreator.java index b72fd31..c4c64c2 100644 --- a/src/main/java/de/rub/nds/scanner/core/report/ReportCreator.java +++ b/src/main/java/de/rub/nds/scanner/core/report/ReportCreator.java @@ -14,16 +14,36 @@ import de.rub.nds.scanner.core.report.container.ReportContainer; import de.rub.nds.scanner.core.report.container.TextContainer; +/** + * Base class for creating report containers from scan results. Provides utility methods for + * creating various types of report containers with appropriate formatting and color schemes. + * + * @param the type of scan report this creator works with + */ public class ReportCreator { protected final PrintingScheme printingScheme; protected final ScannerDetail detail; + /** + * Constructs a new ReportCreator with the specified detail level and printing scheme. + * + * @param detail the level of detail for report generation + * @param scheme the printing scheme defining formatting and colors + */ public ReportCreator(ScannerDetail detail, PrintingScheme scheme) { this.printingScheme = scheme; this.detail = detail; } + /** + * Creates a key-value container for a property with appropriate formatting from the printing + * scheme. + * + * @param property the analyzed property to create a container for + * @param report the scan report containing the property result + * @return a key-value container with formatted text and colors + */ protected ReportContainer createKeyValueContainer(AnalyzedProperty property, ReportT report) { String key = printingScheme.getEncodedKeyText(report, property); String value = printingScheme.getEncodedValueText(report, property); @@ -32,15 +52,35 @@ protected ReportContainer createKeyValueContainer(AnalyzedProperty property, Rep return new KeyValueContainer(key, keyColour, value, valueColour); } + /** + * Creates a key-value container with default colors for both key and value. + * + * @param key the key text + * @param value the value text + * @return a key-value container with default colors + */ protected ReportContainer createDefaultKeyValueContainer(String key, String value) { return new KeyValueContainer(key, AnsiColor.DEFAULT_COLOR, value, AnsiColor.DEFAULT_COLOR); } + /** + * Creates a key-value container with a hexadecimal formatted value and default colors. + * + * @param key the key text + * @param value the hexadecimal value (without "0x" prefix) + * @return a key-value container with the value prefixed with "0x" + */ protected ReportContainer createDefaultKeyHexValueContainer(String key, String value) { return new KeyValueContainer( key, AnsiColor.DEFAULT_COLOR, "0x" + value, AnsiColor.DEFAULT_COLOR); } + /** + * Creates a text container with default color. + * + * @param text the text content + * @return a text container with default color + */ protected TextContainer createDefaultTextContainer(String text) { return new TextContainer(text, AnsiColor.DEFAULT_COLOR); } diff --git a/src/main/java/de/rub/nds/scanner/core/report/ReportPrinter.java b/src/main/java/de/rub/nds/scanner/core/report/ReportPrinter.java index 0caad9b..f18add4 100644 --- a/src/main/java/de/rub/nds/scanner/core/report/ReportPrinter.java +++ b/src/main/java/de/rub/nds/scanner/core/report/ReportPrinter.java @@ -11,6 +11,12 @@ import de.rub.nds.scanner.core.config.ScannerDetail; import de.rub.nds.scanner.core.probe.AnalyzedProperty; +/** + * Abstract base class for generating formatted text representations of scan reports. Provides + * utility methods for formatting output with optional ANSI color codes. + * + * @param the type of scan report this printer works with + */ public abstract class ReportPrinter { protected final ScannerDetail detail; @@ -21,6 +27,14 @@ public abstract class ReportPrinter { protected final ReportT report; + /** + * Constructs a new ReportPrinter with the specified configuration. + * + * @param detail the level of detail for report generation + * @param scheme the printing scheme defining formatting and colors + * @param printColorful whether to include ANSI color codes in the output + * @param scanReport the scan report to print + */ public ReportPrinter( ScannerDetail detail, PrintingScheme scheme, @@ -32,34 +46,82 @@ public ReportPrinter( this.report = scanReport; } + /** + * Generates the complete formatted report as a string. + * + * @return the full report text with optional color formatting + */ public abstract String getFullReport(); + /** + * Formats a string value without color (black text). + * + * @param value the value to format, or null + * @param format the format string for String.format() + * @return the formatted string, with "Unknown" if value is null + */ protected String getBlackString(String value, String format) { return String.format(format, value == null ? "Unknown" : value); } + /** + * Formats a string value with green color if colors are enabled. + * + * @param value the value to format, or null + * @param format the format string for String.format() + * @return the formatted string with optional green color, "Unknown" if value is null + */ protected String getGreenString(String value, String format) { return (printColorful ? AnsiColor.GREEN.getCode() : AnsiColor.RESET.getCode()) + String.format(format, value == null ? "Unknown" : value) + AnsiColor.RESET.getCode(); } + /** + * Formats a string value with yellow color if colors are enabled. + * + * @param value the value to format, or null + * @param format the format string for String.format() + * @return the formatted string with optional yellow color, "Unknown" if value is null + */ protected String getYellowString(String value, String format) { return (printColorful ? AnsiColor.YELLOW.getCode() : AnsiColor.RESET.getCode()) + String.format(format, value == null ? "Unknown" : value) + AnsiColor.RESET.getCode(); } + /** + * Formats a string value with red color if colors are enabled. + * + * @param value the value to format, or null + * @param format the format string for String.format() + * @return the formatted string with optional red color, "Unknown" if value is null + */ protected String getRedString(String value, String format) { return (printColorful ? AnsiColor.RED.getCode() : AnsiColor.RESET.getCode()) + String.format(format, value == null ? "Unknown" : value) + AnsiColor.RESET.getCode(); } + /** + * Appends a value to the builder with a newline. + * + * @param builder the StringBuilder to append to + * @param value the value to append, or null + * @return the builder for method chaining + */ protected StringBuilder prettyAppend(StringBuilder builder, String value) { return builder.append(value == null ? "Unknown" : value).append("\n"); } + /** + * Appends a value to the builder with optional color and a newline. + * + * @param builder the StringBuilder to append to + * @param value the value to append + * @param color the color to apply if colors are enabled + * @return the builder for method chaining + */ protected StringBuilder prettyAppend(StringBuilder builder, String value, AnsiColor color) { if (printColorful) { builder.append(color.getCode()); @@ -72,6 +134,14 @@ protected StringBuilder prettyAppend(StringBuilder builder, String value, AnsiCo return builder; } + /** + * Appends a name-value pair with the value formatted as hexadecimal. + * + * @param builder the StringBuilder to append to + * @param name the property name + * @param value the hexadecimal value (without "0x" prefix), or null + * @return the builder for method chaining + */ protected StringBuilder prettyAppendHexString( StringBuilder builder, String name, String value) { return builder.append(addIndentations(name)) @@ -80,6 +150,14 @@ protected StringBuilder prettyAppendHexString( .append("\n"); } + /** + * Appends a name-value pair with proper indentation. + * + * @param builder the StringBuilder to append to + * @param name the property name + * @param value the property value, or null + * @return the builder for method chaining + */ protected StringBuilder prettyAppend(StringBuilder builder, String name, String value) { return builder.append(addIndentations(name)) .append(": ") @@ -87,6 +165,14 @@ protected StringBuilder prettyAppend(StringBuilder builder, String name, String .append("\n"); } + /** + * Appends a name-value pair for a Long value with proper indentation. + * + * @param builder the StringBuilder to append to + * @param name the property name + * @param value the Long value, or null + * @return the builder for method chaining + */ protected StringBuilder prettyAppend(StringBuilder builder, String name, Long value) { return builder.append(addIndentations(name)) .append(": ") @@ -94,6 +180,14 @@ protected StringBuilder prettyAppend(StringBuilder builder, String name, Long va .append("\n"); } + /** + * Appends a name-value pair for a Boolean value with proper indentation. + * + * @param builder the StringBuilder to append to + * @param name the property name + * @param value the Boolean value, or null + * @return the builder for method chaining + */ protected StringBuilder prettyAppend(StringBuilder builder, String name, Boolean value) { return builder.append(addIndentations(name)) .append(": ") @@ -101,6 +195,14 @@ protected StringBuilder prettyAppend(StringBuilder builder, String name, Boolean .append("\n"); } + /** + * Appends a name-value pair for an analyzed property using the printing scheme. + * + * @param builder the StringBuilder to append to + * @param name the display name + * @param property the analyzed property to format + * @return the builder for method chaining + */ protected StringBuilder prettyAppend( StringBuilder builder, String name, AnalyzedProperty property) { builder.append(addIndentations(name)).append(": "); @@ -109,11 +211,29 @@ protected StringBuilder prettyAppend( return builder; } + /** + * Appends a name-value pair for a Boolean with optional color. + * + * @param builder the StringBuilder to append to + * @param name the property name + * @param value the Boolean value + * @param color the color to apply if colors are enabled + * @return the builder for method chaining + */ protected StringBuilder prettyAppend( StringBuilder builder, String name, Boolean value, AnsiColor color) { return prettyAppend(builder, name, String.valueOf(value), color); } + /** + * Appends a name-value pair with optional color. + * + * @param builder the StringBuilder to append to + * @param name the property name + * @param value the property value + * @param color the color to apply if colors are enabled + * @return the builder for method chaining + */ protected StringBuilder prettyAppend( StringBuilder builder, String name, String value, AnsiColor color) { builder.append(addIndentations(name)).append(": "); @@ -128,6 +248,13 @@ protected StringBuilder prettyAppend( return builder; } + /** + * Appends a main heading with formatting and resets the indentation depth. + * + * @param builder the StringBuilder to append to + * @param value the heading text + * @return the builder for method chaining + */ protected StringBuilder prettyAppendHeading(StringBuilder builder, String value) { depth = 0; @@ -141,6 +268,14 @@ protected StringBuilder prettyAppendHeading(StringBuilder builder, String value) .append(AnsiColor.RESET.getCode()); } + /** + * Appends a name-value pair with the value underlined if colors are enabled. + * + * @param builder the StringBuilder to append to + * @param name the property name + * @param value the property value + * @return the builder for method chaining + */ protected StringBuilder prettyAppendUnderlined( StringBuilder builder, String name, String value) { return builder.append(addIndentations(name)) @@ -152,6 +287,14 @@ protected StringBuilder prettyAppendUnderlined( .append("\n"); } + /** + * Appends a name-value pair for a boolean with the value underlined if colors are enabled. + * + * @param builder the StringBuilder to append to + * @param name the property name + * @param value the boolean value + * @return the builder for method chaining + */ protected StringBuilder prettyAppendUnderlined( StringBuilder builder, String name, boolean value) { return builder.append(addIndentations(name)) @@ -163,6 +306,14 @@ protected StringBuilder prettyAppendUnderlined( .append("\n"); } + /** + * Appends a name-value pair for a long with the value underlined if colors are enabled. + * + * @param builder the StringBuilder to append to + * @param name the property name + * @param value the long value + * @return the builder for method chaining + */ protected StringBuilder prettyAppendUnderlined(StringBuilder builder, String name, long value) { return builder.append(addIndentations(name)) .append(": ") @@ -173,6 +324,13 @@ protected StringBuilder prettyAppendUnderlined(StringBuilder builder, String nam .append("\n"); } + /** + * Appends a subheading with formatting and sets indentation depth to 1. + * + * @param builder the StringBuilder to append to + * @param name the subheading text + * @return the builder for method chaining + */ protected StringBuilder prettyAppendSubheading(StringBuilder builder, String name) { depth = 1; return builder.append("--|") @@ -187,6 +345,13 @@ protected StringBuilder prettyAppendSubheading(StringBuilder builder, String nam : name + "\n\n"); } + /** + * Appends a sub-subheading with formatting and sets indentation depth to 2. + * + * @param builder the StringBuilder to append to + * @param name the sub-subheading text + * @return the builder for method chaining + */ protected StringBuilder prettyAppendSubSubheading(StringBuilder builder, String name) { depth = 2; return builder.append("----|") @@ -201,6 +366,13 @@ protected StringBuilder prettyAppendSubSubheading(StringBuilder builder, String : name + "\n\n"); } + /** + * Appends a sub-sub-subheading with formatting and sets indentation depth to 3. + * + * @param builder the StringBuilder to append to + * @param name the sub-sub-subheading text + * @return the builder for method chaining + */ protected StringBuilder prettyAppendSubSubSubheading(StringBuilder builder, String name) { depth = 3; return builder.append("------|") @@ -215,6 +387,13 @@ protected StringBuilder prettyAppendSubSubSubheading(StringBuilder builder, Stri : name + "\n\n"); } + /** + * Pads a string to the specified length with spaces. + * + * @param value the string to pad + * @param length the desired length + * @return the padded string + */ protected String padToLength(String value, int length) { StringBuilder builder = new StringBuilder(value); while (builder.length() < length) { @@ -223,6 +402,12 @@ protected String padToLength(String value, int length) { return builder.toString(); } + /** + * Adds indentation based on the current depth and tabs for alignment. + * + * @param value the string to indent + * @return the indented string with appropriate tabs for alignment + */ protected String addIndentations(String value) { StringBuilder builder = new StringBuilder(); builder.append(" ".repeat(Math.max(0, depth))); @@ -241,6 +426,11 @@ protected String addIndentations(String value) { return builder.toString(); } + /** + * Sets the current indentation depth for formatting. + * + * @param depth the indentation depth (0 for no indent, higher values for deeper nesting) + */ public void setDepth(int depth) { this.depth = depth; } diff --git a/src/main/java/de/rub/nds/scanner/core/report/ScanReport.java b/src/main/java/de/rub/nds/scanner/core/report/ScanReport.java index 24c3719..7057f18 100644 --- a/src/main/java/de/rub/nds/scanner/core/report/ScanReport.java +++ b/src/main/java/de/rub/nds/scanner/core/report/ScanReport.java @@ -43,6 +43,10 @@ import java.util.Set; import java.util.stream.Collectors; +/** + * Abstract base class representing the results of a security scan. Contains analyzed properties, + * extracted values, guideline compliance reports, and performance metrics. + */ @JsonTypeInfo(use = JsonTypeInfo.Id.CLASS, include = JsonTypeInfo.As.PROPERTY, property = "@class") public abstract class ScanReport { @@ -67,6 +71,7 @@ public abstract class ScanReport { private Long scanStartTime; private Long scanEndTime; + /** Constructs a new ScanReport with empty collections. */ protected ScanReport() { resultMap = new HashMap<>(); extractedValueContainerMap = new HashMap<>(); @@ -76,23 +81,58 @@ protected ScanReport() { unexecutedProbes = new HashSet<>(); } + /** + * Serializes this report to JSON format. + * + * @param outputStream the output stream to write the JSON to + */ public abstract void serializeToJson(OutputStream outputStream); + /** + * Returns the name of the remote entity that was scanned. + * + * @return the remote name (e.g., hostname, IP address) + */ public abstract String getRemoteName(); + /** + * Returns an unmodifiable view of all test results. + * + * @return map of analyzed properties to their test results + */ public synchronized Map getResultMap() { return Collections.unmodifiableMap(resultMap); } + /** + * Returns the test result for a specific property. + * + * @param property the property to get the result for + * @return the test result, or NOT_TESTED_YET if not found + */ public synchronized TestResult getResult(AnalyzedProperty property) { return resultMap.getOrDefault(property, TestResults.NOT_TESTED_YET); } + /** + * Returns the result as an ObjectResult if it is of that type. + * + * @param property the property to get the result for + * @return the ObjectResult, or null if not found or not an ObjectResult + */ public synchronized ObjectResult getObjectResult(AnalyzedProperty property) { TestResult result = resultMap.get(property); return result instanceof ObjectResult ? (ObjectResult) result : null; } + /** + * Returns the result as a typed ObjectResult if it matches the expected type. + * + * @param the expected value type + * @param property the property to get the result for + * @param valueClass the expected class of the value + * @return the typed ObjectResult, or null if not found or type mismatch + */ public synchronized ObjectResult getObjectResult( AnalyzedProperty property, Class valueClass) { ObjectResult result = getObjectResult(property); @@ -105,31 +145,69 @@ public synchronized ObjectResult getObjectResult( } } + /** + * Returns the result as a BigIntegerResult if it is of that type. + * + * @param property the property to get the result for + * @return the BigIntegerResult, or null if not found or not a BigIntegerResult + */ public synchronized BigIntegerResult getBigIntegerResult(AnalyzedProperty property) { TestResult result = resultMap.get(property); return result instanceof BigIntegerResult ? (BigIntegerResult) result : null; } + /** + * Returns the result as an IntegerResult if it is of that type. + * + * @param property the property to get the result for + * @return the IntegerResult, or null if not found or not an IntegerResult + */ public synchronized IntegerResult getIntegerResult(AnalyzedProperty property) { TestResult result = resultMap.get(property); return result instanceof IntegerResult ? (IntegerResult) result : null; } + /** + * Returns the result as a LongResult if it is of that type. + * + * @param property the property to get the result for + * @return the LongResult, or null if not found or not a LongResult + */ public synchronized LongResult getLongResult(AnalyzedProperty property) { TestResult result = resultMap.get(property); return result instanceof LongResult ? (LongResult) result : null; } + /** + * Returns the result as a StringResult if it is of that type. + * + * @param property the property to get the result for + * @return the StringResult, or null if not found or not a StringResult + */ public synchronized StringResult getStringResult(AnalyzedProperty property) { TestResult result = resultMap.get(property); return result instanceof StringResult ? (StringResult) result : null; } + /** + * Returns the result as a CollectionResult if it is of that type. + * + * @param property the property to get the result for + * @return the CollectionResult, or null if not found or not a CollectionResult + */ public synchronized CollectionResult getCollectionResult(AnalyzedProperty property) { TestResult result = resultMap.get(property); return result instanceof CollectionResult ? (CollectionResult) result : null; } + /** + * Returns the result as a typed CollectionResult if it matches the expected element type. + * + * @param the expected element type + * @param property the property to get the result for + * @param valueClass the expected class of collection elements + * @return the typed CollectionResult, or null if not found or type mismatch + */ public synchronized CollectionResult getCollectionResult( AnalyzedProperty property, Class valueClass) { CollectionResult result = getCollectionResult(property); @@ -150,11 +228,25 @@ public synchronized CollectionResult getCollectionResult( } } + /** + * Returns the result as a ListResult if it is of that type. + * + * @param property the property to get the result for + * @return the ListResult, or null if not found or not a ListResult + */ public synchronized ListResult getListResult(AnalyzedProperty property) { TestResult result = resultMap.get(property); return result instanceof ListResult ? (ListResult) result : null; } + /** + * Returns the result as a typed ListResult if it matches the expected element type. + * + * @param the expected element type + * @param property the property to get the result for + * @param valueClass the expected class of list elements + * @return the typed ListResult, or null if not found or type mismatch + */ public synchronized ListResult getListResult( AnalyzedProperty property, Class valueClass) { ListResult result = getListResult(property); @@ -175,16 +267,40 @@ public synchronized ListResult getListResult( } } + /** + * Returns the result as a MapResult if it is of that type. + * + * @param property the property to get the result for + * @return the MapResult, or null if not found or not a MapResult + */ public synchronized MapResult getMapResult(AnalyzedProperty property) { TestResult result = resultMap.get(property); return result instanceof MapResult ? (MapResult) result : null; } + /** + * Returns the result as a MapResult with typed values. + * + * @param the expected value type + * @param property the property to get the result for + * @param valueClass the expected class of map values + * @return the typed MapResult, or null if not found or type mismatch + */ public synchronized MapResult getMapResult( AnalyzedProperty property, Class valueClass) { return getMapResult(property, Object.class, valueClass); } + /** + * Returns the result as a fully typed MapResult. + * + * @param the expected key type + * @param the expected value type + * @param property the property to get the result for + * @param keyClass the expected class of map keys + * @param valueClass the expected class of map values + * @return the typed MapResult, or null if not found or type mismatch + */ public synchronized MapResult getMapResult( AnalyzedProperty property, Class keyClass, Class valueClass) { MapResult result = getMapResult(property); @@ -206,11 +322,25 @@ public synchronized MapResult getMapResult( return new MapResult<>(result.getProperty(), Collections.unmodifiableMap(typedMap)); } + /** + * Returns the result as a SetResult if it is of that type. + * + * @param property the property to get the result for + * @return the SetResult, or null if not found or not a SetResult + */ public synchronized SetResult getSetResult(AnalyzedProperty property) { TestResult result = resultMap.get(property); return result instanceof SetResult ? (SetResult) result : null; } + /** + * Returns the result as a typed SetResult if it matches the expected element type. + * + * @param the expected element type + * @param property the property to get the result for + * @param valueClass the expected class of set elements + * @return the typed SetResult, or null if not found or type mismatch + */ public synchronized SetResult getSetResult( AnalyzedProperty property, Class valueClass) { SetResult result = getSetResult(property); @@ -231,12 +361,24 @@ public synchronized SetResult getSetResult( } } + /** + * Stores a test result for a property and notifies listeners of the change. + * + * @param property the property to store the result for + * @param result the test result to store + */ public synchronized void putResult(AnalyzedProperty property, TestResult result) { TestResult oldResult = resultMap.get(property); resultMap.put(property, result); propertyChangeSupport.firePropertyChange(property.toString(), oldResult, result); } + /** + * Stores a Boolean result for a property, converting it to appropriate TestResult. + * + * @param property the property to store the result for + * @param result the Boolean value (TRUE, FALSE, or null for UNCERTAIN) + */ public synchronized void putResult(AnalyzedProperty property, Boolean result) { this.putResult( property, @@ -247,163 +389,363 @@ public synchronized void putResult(AnalyzedProperty property, Boolean result) { : TestResults.UNCERTAIN); } + /** + * Stores a BigInteger result for a property. + * + * @param property the property to store the result for + * @param result the BigInteger value + */ public synchronized void putResult(AnalyzedProperty property, BigInteger result) { this.putResult(property, new BigIntegerResult(property, result)); } + /** + * Stores an Integer result for a property. + * + * @param property the property to store the result for + * @param result the Integer value + */ public synchronized void putResult(AnalyzedProperty property, Integer result) { this.putResult(property, new IntegerResult(property, result)); } + /** + * Stores a Long result for a property. + * + * @param property the property to store the result for + * @param result the Long value + */ public synchronized void putResult(AnalyzedProperty property, Long result) { this.putResult(property, new LongResult(property, result)); } + /** + * Stores a String result for a property. + * + * @param property the property to store the result for + * @param result the String value + */ public synchronized void putResult(AnalyzedProperty property, String result) { this.putResult(property, new StringResult(property, result)); } + /** + * Stores a List result for a property. + * + * @param property the property to store the result for + * @param result the List value + */ public synchronized void putResult(AnalyzedProperty property, List result) { this.putResult(property, new ListResult<>(property, result)); } + /** + * Stores a Set result for a property. + * + * @param property the property to store the result for + * @param result the Set value + */ public synchronized void putResult(AnalyzedProperty property, Set result) { this.putResult(property, new SetResult<>(property, result)); } + /** + * Stores a Map result for a property. + * + * @param property the property to store the result for + * @param result the Map value + */ public synchronized void putResult(AnalyzedProperty property, Map result) { this.putResult(property, new MapResult<>(property, result)); } + /** + * Stores a generic object result for a property. + * + * @param the type of the result + * @param property the property to store the result for + * @param result the object value + */ public synchronized void putResult(AnalyzedProperty property, T result) { this.putResult(property, new ObjectResult<>(property, result)); } + /** + * Removes a test result for a property and notifies listeners. + * + * @param property the property to remove the result for + */ public synchronized void removeResult(AnalyzedProperty property) { TestResult oldResult = resultMap.remove(property); propertyChangeSupport.firePropertyChange(property.toString(), oldResult, null); } + /** + * Returns an unmodifiable view of all extracted values from the scan. + * + * @return map of trackable values to their containers + */ public synchronized Map> getExtractedValueContainerMap() { return Collections.unmodifiableMap(extractedValueContainerMap); } + /** + * Returns the extracted value container for a specific trackable value. + * + * @param trackableValue the value to get the container for + * @return the extracted value container, or null if not found + */ public synchronized ExtractedValueContainer getExtractedValueContainer( TrackableValue trackableValue) { return extractedValueContainerMap.get(trackableValue); } + /** + * Returns the extracted value container for a specific trackable value with type casting. + * + * @param the expected value type + * @param trackableValue the value to get the container for + * @param valueClass the expected class of the value (for type safety) + * @return the typed extracted value container, or null if not found + */ public synchronized ExtractedValueContainer getExtractedValueContainer( TrackableValue trackableValue, Class valueClass) { //noinspection unchecked return (ExtractedValueContainer) extractedValueContainerMap.get(trackableValue); } + /** + * Stores an extracted value container. + * + * @param trackableValue the trackable value key + * @param extractedValueContainer the container to store + */ public synchronized void putExtractedValueContainer( TrackableValue trackableValue, ExtractedValueContainer extractedValueContainer) { extractedValueContainerMap.put(trackableValue, extractedValueContainer); } + /** + * Stores multiple extracted value containers at once. + * + * @param extractedValueContainerMap map of containers to store + */ public synchronized void putAllExtractedValueContainers( Map> extractedValueContainerMap) { this.extractedValueContainerMap.putAll(extractedValueContainerMap); } + /** + * Returns an unmodifiable list of guideline compliance reports. + * + * @return list of guideline reports + */ public synchronized List getGuidelineReports() { return Collections.unmodifiableList(guidelineReports); } + /** + * Adds a guideline compliance report to this scan report. + * + * @param guidelineReport the guideline report to add + */ public synchronized void addGuidelineReport(GuidelineReport guidelineReport) { guidelineReports.add(guidelineReport); } + /** + * Returns the overall security score for the scan. + * + * @return the score value, or null if not calculated + */ public synchronized Integer getScore() { return score; } + /** + * Sets the overall security score for the scan. + * + * @param score the score value + */ public synchronized void setScore(Integer score) { this.score = score; } + /** + * Returns the detailed score report. + * + * @return the score report, or null if not generated + */ public synchronized ScoreReport getScoreReport() { return scoreReport; } + /** + * Sets the detailed score report. + * + * @param scoreReport the score report to set + */ public synchronized void setScoreReport(ScoreReport scoreReport) { this.scoreReport = scoreReport; } + /** + * Checks if a probe of the specified type has already been executed. + * + * @param type the probe type to check + * @return true if a probe of this type was executed, false otherwise + */ public synchronized boolean isProbeAlreadyExecuted(ProbeType type) { return getExecutedProbeTypes().contains(type); } + /** + * Returns an unmodifiable list of performance data for executed probes. + * + * @return list of performance data + */ public synchronized List getProbePerformanceData() { return Collections.unmodifiableList(probePerformanceData); } + /** + * Records performance data for a probe execution. + * + * @param performanceData the performance data to record + */ public synchronized void recordProbePerformance(PerformanceData performanceData) { probePerformanceData.add(performanceData); } + /** + * Marks a probe as executed and notifies listeners. + * + * @param probe the probe that was executed + */ public synchronized void markProbeAsExecuted(ScannerProbe probe) { executedProbes.add(probe); propertyChangeSupport.firePropertyChange("supportedProbe", null, probe.getProbeName()); } + /** + * Marks a probe as unexecuted (skipped) and notifies listeners. + * + * @param probe the probe that was not executed + */ public synchronized void markProbeAsUnexecuted(ScannerProbe probe) { unexecutedProbes.add(probe); propertyChangeSupport.firePropertyChange("unsupportedProbe", null, probe.getProbeName()); } + /** + * Returns an unmodifiable set of all executed probes. + * + * @return set of executed probes + */ public synchronized Set> getExecutedProbes() { return Collections.unmodifiableSet(executedProbes); } + /** + * Returns the types of all executed probes. + * + * @return set of executed probe types + */ public synchronized Set getExecutedProbeTypes() { return executedProbes.stream() .map(ScannerProbe::getType) .collect(Collectors.toUnmodifiableSet()); } + /** + * Returns an unmodifiable set of all unexecuted (skipped) probes. + * + * @return set of unexecuted probes + */ public synchronized Set> getUnexecutedProbes() { return Collections.unmodifiableSet(unexecutedProbes); } + /** + * Returns the types of all unexecuted probes. + * + * @return set of unexecuted probe types + */ public synchronized Set getUnexecutedProbeTypes() { return unexecutedProbes.stream() .map(ScannerProbe::getType) .collect(Collectors.toUnmodifiableSet()); } + /** + * Returns the total number of network connections performed during the scan. + * + * @return the connection count, or null if not tracked + */ public synchronized Integer getPerformedConnections() { return performedConnections; } + /** + * Sets the total number of network connections performed during the scan. + * + * @param performedConnections the connection count + */ public synchronized void setPerformedConnections(Integer performedConnections) { this.performedConnections = performedConnections; } + /** + * Returns the timestamp when the scan started. + * + * @return the start time in milliseconds since epoch, or null if not set + */ public synchronized Long getScanStartTime() { return scanStartTime; } + /** + * Sets the timestamp when the scan started. + * + * @param scanStartTime the start time in milliseconds since epoch + */ public synchronized void setScanStartTime(Long scanStartTime) { this.scanStartTime = scanStartTime; } + /** + * Returns the timestamp when the scan ended. + * + * @return the end time in milliseconds since epoch, or null if not set + */ public synchronized Long getScanEndTime() { return scanEndTime; } + /** + * Sets the timestamp when the scan ended. + * + * @param scanStopTime the end time in milliseconds since epoch + */ public synchronized void setScanEndTime(Long scanStopTime) { this.scanEndTime = scanStopTime; } + /** + * Adds a property change listener to be notified of report updates. + * + * @param listener the listener to add + */ public synchronized void addPropertyChangeListener(PropertyChangeListener listener) { propertyChangeSupport.addPropertyChangeListener(listener); } + /** + * Removes a property change listener. + * + * @param listener the listener to remove + */ public synchronized void removePropertyChangeListener(PropertyChangeListener listener) { propertyChangeSupport.removePropertyChangeListener(listener); } diff --git a/src/main/java/de/rub/nds/scanner/core/report/TestResultTextEncoder.java b/src/main/java/de/rub/nds/scanner/core/report/TestResultTextEncoder.java index 19aa186..0710457 100644 --- a/src/main/java/de/rub/nds/scanner/core/report/TestResultTextEncoder.java +++ b/src/main/java/de/rub/nds/scanner/core/report/TestResultTextEncoder.java @@ -11,20 +11,45 @@ import de.rub.nds.scanner.core.probe.result.TestResult; import java.util.HashMap; +/** + * Encoder that converts TestResult objects to text representations using a configurable mapping. If + * no mapping is provided or no mapping exists for a result, falls back to the result's name. + */ public class TestResultTextEncoder extends Encoder { private HashMap textEncodingMap = null; + /** + * Constructs a new TestResultTextEncoder with no text mappings. Results will be encoded using + * their getName() method. + */ public TestResultTextEncoder() {} + /** + * Constructs a new TestResultTextEncoder with the specified text mappings. + * + * @param textEncodingMap map of TestResult objects to their text representations + */ public TestResultTextEncoder(HashMap textEncodingMap) { this.textEncodingMap = textEncodingMap; } + /** + * Returns the text encoding map used by this encoder. + * + * @return the map of TestResult to text mappings, or null if no map is set + */ public HashMap getTextEncodingMap() { return textEncodingMap; } + /** + * Encodes a TestResult to its text representation. Uses the text encoding map if available and + * contains a mapping for the result, otherwise returns the result's name. + * + * @param result the TestResult to encode + * @return the text representation of the result + */ @Override public String encode(TestResult result) { if (textEncodingMap == null) { diff --git a/src/main/java/de/rub/nds/scanner/core/report/container/HeadlineContainer.java b/src/main/java/de/rub/nds/scanner/core/report/container/HeadlineContainer.java index 762f906..36fe6cf 100644 --- a/src/main/java/de/rub/nds/scanner/core/report/container/HeadlineContainer.java +++ b/src/main/java/de/rub/nds/scanner/core/report/container/HeadlineContainer.java @@ -11,22 +11,45 @@ import de.rub.nds.scanner.core.config.ScannerDetail; import de.rub.nds.scanner.core.report.AnsiColor; +/** + * Container for displaying headlines in scanner reports. Supports different depth levels with + * corresponding visual formatting and colors. + */ public class HeadlineContainer extends ReportContainer { private static final int NUMBER_OF_DASHES_IN_H_LINE = 50; private final String headline; + /** + * Creates a new HeadlineContainer with normal detail level. + * + * @param headline The headline text to display + */ public HeadlineContainer(String headline) { super(ScannerDetail.NORMAL); this.headline = headline; } + /** + * Creates a new HeadlineContainer with specified detail level. + * + * @param headline The headline text to display + * @param detail The detail level for this container + */ public HeadlineContainer(String headline, ScannerDetail detail) { super(detail); this.headline = headline; } + /** + * Prints the headline to the provided StringBuilder with appropriate formatting. Depth 0 + * headlines include a horizontal line separator. + * + * @param builder The StringBuilder to append the output to + * @param depth The indentation depth level + * @param useColor Whether to use ANSI color codes in the output + */ @Override public void print(StringBuilder builder, int depth, boolean useColor) { if (useColor) { @@ -60,6 +83,11 @@ private static AnsiColor getColorByDepth(int depth) { } } + /** + * Gets the headline text. + * + * @return The headline text + */ public String getHeadline() { return headline; } diff --git a/src/main/java/de/rub/nds/scanner/core/report/container/KeyValueContainer.java b/src/main/java/de/rub/nds/scanner/core/report/container/KeyValueContainer.java index c6c8500..b0f464d 100644 --- a/src/main/java/de/rub/nds/scanner/core/report/container/KeyValueContainer.java +++ b/src/main/java/de/rub/nds/scanner/core/report/container/KeyValueContainer.java @@ -13,6 +13,10 @@ import org.apache.logging.log4j.LogManager; import org.apache.logging.log4j.Logger; +/** + * Container for displaying key-value pairs in scanner reports. Provides formatted output with + * configurable colors for both keys and values. + */ public class KeyValueContainer extends ReportContainer { private static final Logger LOGGER = LogManager.getLogger(); @@ -25,6 +29,14 @@ public class KeyValueContainer extends ReportContainer { private String value; private AnsiColor valueColor; + /** + * Creates a new KeyValueContainer with specified colors. + * + * @param key The key text to display + * @param keyColor The color for the key + * @param value The value text to display + * @param valueColor The color for the value + */ public KeyValueContainer(String key, AnsiColor keyColor, String value, AnsiColor valueColor) { super(ScannerDetail.NORMAL); this.key = key; @@ -33,6 +45,14 @@ public KeyValueContainer(String key, AnsiColor keyColor, String value, AnsiColor this.valueColor = valueColor; } + /** + * Prints the key-value pair to the provided StringBuilder. The key is padded to ensure + * consistent alignment. + * + * @param builder The StringBuilder to append the output to + * @param depth The indentation depth level + * @param useColor Whether to use ANSI color codes in the output + */ @Override public void print(StringBuilder builder, int depth, boolean useColor) { addDepth(builder, depth); @@ -58,34 +78,74 @@ private static String pad(String text, int size) { } } + /** + * Gets the key text. + * + * @return The key text + */ public String getKey() { return key; } + /** + * Sets the key text. + * + * @param key The new key text + */ public void setKey(String key) { this.key = key; } + /** + * Gets the key color. + * + * @return The ANSI color for the key + */ public AnsiColor getKeyColor() { return keyColor; } + /** + * Sets the key color. + * + * @param keyColor The new ANSI color for the key + */ public void setKeyColor(AnsiColor keyColor) { this.keyColor = keyColor; } + /** + * Gets the value text. + * + * @return The value text + */ public String getValue() { return value; } + /** + * Sets the value text. + * + * @param value The new value text + */ public void setValue(String value) { this.value = value; } + /** + * Gets the value color. + * + * @return The ANSI color for the value + */ public AnsiColor getValueColor() { return valueColor; } + /** + * Sets the value color. + * + * @param valueColor The new ANSI color for the value + */ public void setValueColor(AnsiColor valueColor) { this.valueColor = valueColor; } diff --git a/src/main/java/de/rub/nds/scanner/core/report/container/ListContainer.java b/src/main/java/de/rub/nds/scanner/core/report/container/ListContainer.java index ee9cdd4..d5e45c6 100644 --- a/src/main/java/de/rub/nds/scanner/core/report/container/ListContainer.java +++ b/src/main/java/de/rub/nds/scanner/core/report/container/ListContainer.java @@ -12,42 +12,77 @@ import java.util.LinkedList; import java.util.List; +/** + * Container for managing a list of report containers. Supports depth increase for nested + * indentation of child containers. + */ public class ListContainer extends ReportContainer { private final List reportContainerList; private final int depthIncrease; + /** Creates a new empty ListContainer with no depth increase. */ public ListContainer() { super(ScannerDetail.NORMAL); this.reportContainerList = new LinkedList<>(); this.depthIncrease = 0; } + /** + * Creates a new empty ListContainer with specified depth increase. + * + * @param depthIncrease The amount to increase depth when printing child containers + */ public ListContainer(int depthIncrease) { super(ScannerDetail.NORMAL); this.reportContainerList = new LinkedList<>(); this.depthIncrease = depthIncrease; } + /** + * Creates a new ListContainer with existing containers and specified depth increase. + * + * @param reportContainerList The initial list of report containers + * @param depthIncrease The amount to increase depth when printing child containers + */ public ListContainer(List reportContainerList, int depthIncrease) { super(ScannerDetail.NORMAL); this.reportContainerList = reportContainerList; this.depthIncrease = depthIncrease; } + /** + * Creates a new ListContainer with existing containers and no depth increase. + * + * @param reportContainerList The initial list of report containers + */ public ListContainer(List reportContainerList) { super(ScannerDetail.NORMAL); this.reportContainerList = reportContainerList; this.depthIncrease = 0; } + /** + * Prints all contained report containers to the provided StringBuilder. Each container is + * printed with the specified depth plus any depth increase. + * + * @param builder The StringBuilder to append the output to + * @param depth The indentation depth level + * @param useColor Whether to use ANSI color codes in the output + */ @Override public void print(StringBuilder builder, int depth, boolean useColor) { reportContainerList.forEach( container -> container.print(builder, depth + depthIncrease, useColor)); } + /** + * Adds a report container to this list. + * + * @param container The container to add + * @return This ListContainer instance for method chaining + */ public ListContainer add(ReportContainer container) { this.reportContainerList.add(container); return this; diff --git a/src/main/java/de/rub/nds/scanner/core/report/container/ReportContainer.java b/src/main/java/de/rub/nds/scanner/core/report/container/ReportContainer.java index 5c607bb..d9878ed 100644 --- a/src/main/java/de/rub/nds/scanner/core/report/container/ReportContainer.java +++ b/src/main/java/de/rub/nds/scanner/core/report/container/ReportContainer.java @@ -11,21 +11,52 @@ import de.rub.nds.scanner.core.config.ScannerDetail; import de.rub.nds.scanner.core.report.AnsiColor; +/** + * Abstract base class for all report containers in the scanner framework. Provides common + * functionality for printing formatted reports with indentation and color support. + */ public abstract class ReportContainer { private final ScannerDetail detail; + /** + * Creates a new ReportContainer with the specified detail level. + * + * @param detail The detail level for this container + */ public ReportContainer(ScannerDetail detail) { this.detail = detail; } + /** + * Prints this container's content to the provided StringBuilder. + * + * @param builder The StringBuilder to append the output to + * @param depth The indentation depth level + * @param useColor Whether to use ANSI color codes in the output + */ public abstract void print(StringBuilder builder, int depth, boolean useColor); + /** + * Adds indentation spaces based on the specified depth. Each depth level adds two spaces. + * + * @param builder The StringBuilder to append to + * @param depth The indentation depth level + * @return The modified StringBuilder for method chaining + */ protected StringBuilder addDepth(StringBuilder builder, int depth) { builder.append(" ".repeat(Math.max(0, depth))); return builder; } + /** + * Adds headline-specific indentation based on the specified depth. Uses dashes and pipes for + * visual hierarchy. + * + * @param builder The StringBuilder to append to + * @param depth The indentation depth level + * @return The modified StringBuilder for method chaining + */ protected StringBuilder addHeadlineDepth(StringBuilder builder, int depth) { builder.append("--".repeat(Math.max(0, depth))); if (depth > 0) { @@ -34,6 +65,15 @@ protected StringBuilder addHeadlineDepth(StringBuilder builder, int depth) { return builder; } + /** + * Adds colored text to the StringBuilder if color is enabled. + * + * @param builder The StringBuilder to append to + * @param color The ANSI color to apply + * @param text The text to colorize + * @param useColor Whether to apply color codes + * @return The modified StringBuilder for method chaining + */ protected StringBuilder addColor( StringBuilder builder, AnsiColor color, String text, boolean useColor) { if (useColor) { @@ -44,6 +84,11 @@ protected StringBuilder addColor( return builder; } + /** + * Gets the detail level for this container. + * + * @return The scanner detail level + */ public ScannerDetail getDetail() { return detail; } diff --git a/src/main/java/de/rub/nds/scanner/core/report/container/TableContainer.java b/src/main/java/de/rub/nds/scanner/core/report/container/TableContainer.java index 95e3383..559ba69 100644 --- a/src/main/java/de/rub/nds/scanner/core/report/container/TableContainer.java +++ b/src/main/java/de/rub/nds/scanner/core/report/container/TableContainer.java @@ -13,6 +13,10 @@ import java.util.LinkedList; import java.util.List; +/** + * Container for displaying tabular data in scanner reports. Supports automatic column alignment and + * formatting with headers. + */ public class TableContainer extends ReportContainer { private List headlineList; @@ -21,36 +25,68 @@ public class TableContainer extends ReportContainer { private int depthIncrease; + /** Creates a new empty TableContainer with normal detail level and no depth increase. */ public TableContainer() { super(ScannerDetail.NORMAL); this.depthIncrease = 0; this.containerTable = new LinkedList<>(); } + /** + * Creates a new empty TableContainer with specified detail level. + * + * @param detail The detail level for this container + */ public TableContainer(ScannerDetail detail) { super(detail); this.depthIncrease = 0; this.containerTable = new LinkedList<>(); } + /** + * Creates a new empty TableContainer with specified depth increase. + * + * @param depthIncrease The amount to increase depth when printing + */ public TableContainer(int depthIncrease) { super(ScannerDetail.NORMAL); this.depthIncrease = depthIncrease; this.containerTable = new LinkedList<>(); } + /** + * Creates a new empty TableContainer with specified detail level and depth increase. + * + * @param detail The detail level for this container + * @param depthIncrease The amount to increase depth when printing + */ public TableContainer(ScannerDetail detail, int depthIncrease) { super(detail); this.depthIncrease = depthIncrease; this.containerTable = new LinkedList<>(); } + /** + * Prints the table to the provided StringBuilder with a trailing newline. + * + * @param builder The StringBuilder to append the output to + * @param depth The indentation depth level + * @param useColor Whether to use ANSI color codes in the output + */ @Override public void print(StringBuilder builder, int depth, boolean useColor) { println(builder, depth, useColor); builder.append("\n"); } + /** + * Prints the table to the provided StringBuilder without a trailing newline. Includes headers, + * separator line, and all data rows with proper column alignment. + * + * @param builder The StringBuilder to append the output to + * @param depth The indentation depth level + * @param useColor Whether to use ANSI color codes in the output + */ public void println(StringBuilder builder, int depth, boolean useColor) { List paddings = getColumnPaddings(); printTableLine(headlineList, paddings, builder, depth, useColor); @@ -108,30 +144,65 @@ private void printStripline(List paddings, StringBuilder builder, int d builder.append("\n"); } + /** + * Adds a new row to the table. + * + * @param line A list of TextContainers representing the cells in the row + */ public void addLineToTable(List line) { this.containerTable.add(line); } + /** + * Gets the list of table headers. + * + * @return The list of TextContainers representing the table headers + */ public List getHeadlineList() { return headlineList; } + /** + * Sets the list of table headers. + * + * @param headlineList The list of TextContainers representing the table headers + */ public void setHeadlineList(List headlineList) { this.headlineList = headlineList; } + /** + * Gets the table data as a list of rows. + * + * @return The list of rows, where each row is a list of TextContainers + */ public List> getContainerTable() { return containerTable; } + /** + * Sets the table data. + * + * @param containerTable The list of rows, where each row is a list of TextContainers + */ public void setContainerTable(List> containerTable) { this.containerTable = containerTable; } + /** + * Gets the depth increase value. + * + * @return The amount of depth increase when printing + */ public int getDepthIncrease() { return depthIncrease; } + /** + * Sets the depth increase value. + * + * @param depthIncrease The amount of depth increase when printing + */ public void setDepthIncrease(int depthIncrease) { this.depthIncrease = depthIncrease; } diff --git a/src/main/java/de/rub/nds/scanner/core/report/container/TextContainer.java b/src/main/java/de/rub/nds/scanner/core/report/container/TextContainer.java index cb6119f..ee42c06 100644 --- a/src/main/java/de/rub/nds/scanner/core/report/container/TextContainer.java +++ b/src/main/java/de/rub/nds/scanner/core/report/container/TextContainer.java @@ -11,34 +11,70 @@ import de.rub.nds.scanner.core.config.ScannerDetail; import de.rub.nds.scanner.core.report.AnsiColor; +/** + * Container for displaying simple text in scanner reports. Supports colored text output with + * configurable detail levels. + */ public class TextContainer extends ReportContainer { private final String text; private final AnsiColor color; + /** + * Creates a new TextContainer with normal detail level. + * + * @param text The text to display + * @param color The ANSI color for the text + */ public TextContainer(String text, AnsiColor color) { super(ScannerDetail.NORMAL); this.text = text; this.color = color; } + /** + * Creates a new TextContainer with specified detail level. + * + * @param text The text to display + * @param color The ANSI color for the text + * @param detail The detail level for this container + */ public TextContainer(String text, AnsiColor color, ScannerDetail detail) { super(detail); this.text = text; this.color = color; } + /** + * Prints the text to the provided StringBuilder with a trailing newline. + * + * @param builder The StringBuilder to append the output to + * @param depth The indentation depth level + * @param useColor Whether to use ANSI color codes in the output + */ @Override public void print(StringBuilder builder, int depth, boolean useColor) { println(builder, depth, useColor); builder.append("\n"); } + /** + * Prints the text to the provided StringBuilder without a trailing newline. + * + * @param builder The StringBuilder to append the output to + * @param depth The indentation depth level + * @param useColor Whether to use ANSI color codes in the output + */ public void println(StringBuilder builder, int depth, boolean useColor) { addDepth(builder, depth); addColor(builder, color, text, useColor); } + /** + * Gets the text content. + * + * @return The text to be displayed + */ public String getText() { return text; } diff --git a/src/main/java/de/rub/nds/scanner/core/report/rating/PropertyResultRatingInfluencer.java b/src/main/java/de/rub/nds/scanner/core/report/rating/PropertyResultRatingInfluencer.java index 131e9bc..9237a49 100644 --- a/src/main/java/de/rub/nds/scanner/core/report/rating/PropertyResultRatingInfluencer.java +++ b/src/main/java/de/rub/nds/scanner/core/report/rating/PropertyResultRatingInfluencer.java @@ -20,6 +20,11 @@ import jakarta.xml.bind.annotation.XmlType; import java.util.Objects; +/** + * Represents a rating influencer for a specific property result. This class encapsulates how a + * particular test result affects the overall rating score, including potential score caps and + * references to other properties. + */ @XmlRootElement @XmlAccessorType(XmlAccessType.FIELD) @XmlType( @@ -52,10 +57,10 @@ public class PropertyResultRatingInfluencer implements Comparable getPropertyRatingInfluencers() { } /** - * Sets the property rating influencers. + * Sets the list of property result rating influencers. * * @param propertyRatingInfluencers the list of property rating influencers to set */ @@ -93,7 +99,7 @@ public void setPropertyRatingInfluencers( } /** - * Adds a property rating influencer to the list. + * Adds a property result rating influencer to the list. * * @param ratingInfluence the property rating influencer to add */ @@ -102,11 +108,12 @@ public void addPropertyRatingInfluencer(PropertyResultRatingInfluencer ratingInf } /** - * Gets the property rating influencer for a specific test result. If no matching influencer is - * found, returns a default influencer with 0 influence. + * Gets the property rating influencer for a specific test result. If no influencer is found for + * the given result, returns a new influencer with zero influence. * * @param result the test result to find an influencer for - * @return the matching property rating influencer or a default one with 0 influence + * @return the matching property rating influencer, or a new one with zero influence if not + * found */ public PropertyResultRatingInfluencer getPropertyRatingInfluencer(TestResult result) { for (PropertyResultRatingInfluencer ri : propertyRatingInfluencers) { diff --git a/src/main/java/de/rub/nds/scanner/core/report/rating/RatingInfluencers.java b/src/main/java/de/rub/nds/scanner/core/report/rating/RatingInfluencers.java index c61cc5b..0d8620e 100644 --- a/src/main/java/de/rub/nds/scanner/core/report/rating/RatingInfluencers.java +++ b/src/main/java/de/rub/nds/scanner/core/report/rating/RatingInfluencers.java @@ -17,6 +17,11 @@ import java.io.Serializable; import java.util.LinkedList; +/** + * Container class for a collection of rating influencers. This class manages multiple + * RatingInfluencer instances and provides methods to retrieve specific property rating influencers + * based on analyzed properties and test results. + */ @XmlRootElement(name = "ratingInfluencers") @XmlAccessorType(XmlAccessType.FIELD) public class RatingInfluencers implements Serializable { @@ -29,9 +34,9 @@ public class RatingInfluencers implements Serializable { private RatingInfluencers() {} /** - * Constructs a RatingInfluencers with the specified list of rating influencers. + * Constructs a RatingInfluencers container with the specified list of rating influencers. * - * @param ratingInfluencers the list of rating influencers + * @param ratingInfluencers the list of rating influencers to manage */ public RatingInfluencers(LinkedList ratingInfluencers) { this.ratingInfluencers = ratingInfluencers; @@ -40,28 +45,29 @@ public RatingInfluencers(LinkedList ratingInfluencers) { /** * Gets the list of rating influencers. * - * @return the list of rating influencers + * @return the linked list of rating influencers */ public LinkedList getRatingInfluencers() { return ratingInfluencers; } /** - * Sets the rating influencers list. + * Sets the list of rating influencers. * - * @param ratingInfluencers the list of rating influencers to set + * @param ratingInfluencers the linked list of rating influencers to set */ public void setRatingInfluencers(LinkedList ratingInfluencers) { this.ratingInfluencers = ratingInfluencers; } /** - * Gets the property rating influencer for a specific property and test result. If no matching - * influencer is found, returns a default influencer with 0 influence. + * Gets the property rating influencer for a specific analyzed property and test result. If no + * matching rating influencer is found, returns a new influencer with zero influence. * - * @param property the analyzed property to find an influencer for - * @param result the test result to find an influencer for - * @return the matching property rating influencer or a default one with 0 influence + * @param property the analyzed property to search for + * @param result the test result to match + * @return the matching property rating influencer, or a new one with zero influence if not + * found */ public PropertyResultRatingInfluencer getPropertyRatingInfluencer( AnalyzedProperty property, TestResult result) { diff --git a/src/main/java/de/rub/nds/scanner/core/report/rating/RatingInfluencersIO.java b/src/main/java/de/rub/nds/scanner/core/report/rating/RatingInfluencersIO.java index 93e3c59..794c106 100644 --- a/src/main/java/de/rub/nds/scanner/core/report/rating/RatingInfluencersIO.java +++ b/src/main/java/de/rub/nds/scanner/core/report/rating/RatingInfluencersIO.java @@ -13,14 +13,19 @@ import jakarta.xml.bind.JAXBException; import java.util.Set; +/** + * Provides XML serialization and deserialization functionality for RatingInfluencers objects. This + * class extends JaxbSerializer to handle the marshalling and unmarshalling of rating influencer + * configurations to and from XML format. + */ public class RatingInfluencersIO extends JaxbSerializer { /** - * Constructs a RatingInfluencersIO with support for the specified AnalyzedProperty class. - * Creates a JAXB serializer configured to handle RatingInfluencers and related classes. + * Constructs a RatingInfluencersIO serializer for the specified analyzed property class. This + * constructor initializes the JAXB context with all necessary classes for serialization. * - * @param analyzedPropertyClass the class of AnalyzedProperty to support in serialization - * @throws JAXBException if JAXB context creation fails + * @param analyzedPropertyClass the class of analyzed properties to include in the JAXB context + * @throws JAXBException if there is an error creating the JAXB context */ public RatingInfluencersIO(Class analyzedPropertyClass) throws JAXBException { diff --git a/src/main/java/de/rub/nds/scanner/core/report/rating/Recommendation.java b/src/main/java/de/rub/nds/scanner/core/report/rating/Recommendation.java index 223ce8c..637a317 100644 --- a/src/main/java/de/rub/nds/scanner/core/report/rating/Recommendation.java +++ b/src/main/java/de/rub/nds/scanner/core/report/rating/Recommendation.java @@ -19,6 +19,11 @@ import java.util.LinkedList; import java.util.List; +/** + * Represents a comprehensive recommendation for an analyzed property. This class contains all + * information needed to provide guidance about a specific property, including descriptions, + * documentation, links, and specific recommendations for different test results. + */ @XmlRootElement @XmlType( propOrder = { @@ -53,7 +58,8 @@ public class Recommendation { private List propertyRecommendations; /** - * Constructs an empty Recommendation with empty lists for property recommendations and links. + * Constructs an empty Recommendation with initialized empty lists for property recommendations + * and links. */ public Recommendation() { propertyRecommendations = new LinkedList<>(); @@ -61,10 +67,11 @@ public Recommendation() { } /** - * Constructs a Recommendation with the specified property and recommendations list. + * Constructs a Recommendation with the specified analyzed property and list of property + * recommendations. * - * @param analyzedProperty the analyzed property this recommendation applies to - * @param propertyRecommendations the list of property result recommendations + * @param analyzedProperty the property this recommendation applies to + * @param propertyRecommendations the list of recommendations for different test results */ public Recommendation( AnalyzedProperty analyzedProperty, @@ -74,10 +81,10 @@ public Recommendation( } /** - * Constructs a Recommendation with a property and short name. + * Constructs a Recommendation with the specified analyzed property and short name. * - * @param analyzedProperty the analyzed property this recommendation applies to - * @param shortName the short name for this recommendation + * @param analyzedProperty the property this recommendation applies to + * @param shortName a short, human-readable name for the property */ public Recommendation(AnalyzedProperty analyzedProperty, String shortName) { this(); @@ -86,13 +93,13 @@ public Recommendation(AnalyzedProperty analyzedProperty, String shortName) { } /** - * Constructs a Recommendation with detailed information. + * Constructs a Recommendation with descriptions and links. * - * @param analyzedProperty the analyzed property this recommendation applies to - * @param shortName the short name for this recommendation - * @param shortDescription the short description of the recommendation - * @param detailedDescription the detailed description of the recommendation - * @param links additional reference links + * @param analyzedProperty the property this recommendation applies to + * @param shortName a short, human-readable name for the property + * @param shortDescription a brief description of the property + * @param detailedDescription a comprehensive description of the property + * @param links relevant links for more information */ public Recommendation( AnalyzedProperty analyzedProperty, @@ -111,11 +118,11 @@ public Recommendation( /** * Constructs a Recommendation with a single property recommendation. * - * @param analyzedProperty the analyzed property this recommendation applies to - * @param shortName the short name for this recommendation - * @param shortDescription the short description of the recommendation - * @param propertyRecommendation the property result recommendation to add - * @param links additional reference links + * @param analyzedProperty the property this recommendation applies to + * @param shortName a short, human-readable name for the property + * @param shortDescription a brief description of the property + * @param propertyRecommendation a recommendation for a specific test result + * @param links relevant links for more information */ public Recommendation( AnalyzedProperty analyzedProperty, @@ -132,14 +139,14 @@ public Recommendation( } /** - * Constructs a Recommendation with detailed information and a single property recommendation. + * Constructs a Recommendation with complete descriptions and a single property recommendation. * - * @param analyzedProperty the analyzed property this recommendation applies to - * @param shortName the short name for this recommendation - * @param shortDescription the short description of the recommendation - * @param detailedDescription the detailed description of the recommendation - * @param propertyRecommendation the property result recommendation to add - * @param links additional reference links + * @param analyzedProperty the property this recommendation applies to + * @param shortName a short, human-readable name for the property + * @param shortDescription a brief description of the property + * @param detailedDescription a comprehensive description of the property + * @param propertyRecommendation a recommendation for a specific test result + * @param links relevant links for more information */ public Recommendation( AnalyzedProperty analyzedProperty, @@ -158,15 +165,15 @@ public Recommendation( } /** - * Constructs a fully-specified Recommendation with all fields. + * Constructs a fully specified Recommendation with all fields. * - * @param analyzedProperty the analyzed property this recommendation applies to - * @param shortName the short name for this recommendation - * @param shortDescription the short description of the recommendation - * @param detailedDescription the detailed description of the recommendation - * @param testDocumentation the test documentation - * @param links the list of reference links - * @param propertyRecommendations the list of property result recommendations + * @param analyzedProperty the property this recommendation applies to + * @param shortName a short, human-readable name for the property + * @param shortDescription a brief description of the property + * @param detailedDescription a comprehensive description of the property + * @param testDocumentation documentation about how the property is tested + * @param links relevant links for more information + * @param propertyRecommendations list of recommendations for different test results */ public Recommendation( AnalyzedProperty analyzedProperty, @@ -186,7 +193,7 @@ public Recommendation( } /** - * Gets the analyzed property this recommendation applies to. + * Gets the analyzed property that this recommendation applies to. * * @return the analyzed property */ @@ -195,7 +202,7 @@ public AnalyzedProperty getAnalyzedProperty() { } /** - * Sets the analyzed property. + * Sets the analyzed property that this recommendation applies to. * * @param analyzedProperty the analyzed property to set */ @@ -204,10 +211,10 @@ public void setAnalyzedProperty(AnalyzedProperty analyzedProperty) { } /** - * Gets the short name of this recommendation. If no short name is set, returns the analyzed - * property's string representation. + * Gets the short name for the property. If no short name is set, returns the string + * representation of the analyzed property. * - * @return the short name or property string if short name is null or empty + * @return the short name or property string representation */ public String getShortName() { if (shortName == null || shortName.equals("")) { @@ -218,7 +225,7 @@ public String getShortName() { } /** - * Sets the short name. + * Sets the short name for the property. * * @param shortName the short name to set */ @@ -227,7 +234,7 @@ public void setShortName(String shortName) { } /** - * Gets the short description of this recommendation. + * Gets the brief description of the property. * * @return the short description */ @@ -236,7 +243,7 @@ public String getShortDescription() { } /** - * Sets the short description. + * Sets the brief description of the property. * * @param shortDescription the short description to set */ @@ -245,7 +252,7 @@ public void setShortDescription(String shortDescription) { } /** - * Gets the detailed description of this recommendation. + * Gets the comprehensive description of the property. * * @return the detailed description */ @@ -254,7 +261,7 @@ public String getDetailedDescription() { } /** - * Sets the detailed description. + * Sets the comprehensive description of the property. * * @param detailedDescription the detailed description to set */ @@ -263,7 +270,7 @@ public void setDetailedDescription(String detailedDescription) { } /** - * Gets the test documentation. + * Gets the documentation about how the property is tested. * * @return the test documentation */ @@ -272,7 +279,7 @@ public String getTestDocumentation() { } /** - * Sets the test documentation. + * Sets the documentation about how the property is tested. * * @param testDocumentation the test documentation to set */ @@ -281,18 +288,18 @@ public void setTestDocumentation(String testDocumentation) { } /** - * Gets the list of property result recommendations. + * Gets the list of recommendations for different test results. * - * @return the list of property recommendations + * @return the list of property result recommendations */ public List getPropertyRecommendations() { return propertyRecommendations; } /** - * Sets the property recommendations. + * Sets the list of recommendations for different test results. * - * @param propertyRecommendations the list of property recommendations to set + * @param propertyRecommendations the list of property result recommendations to set */ public void setPropertyRecommendations( List propertyRecommendations) { @@ -300,12 +307,11 @@ public void setPropertyRecommendations( } /** - * Gets the property result recommendation for a specific test result. If no matching - * recommendation is found, returns a default recommendation with NO_INFORMATION_FOUND and - * NO_RECOMMENDATION_FOUND messages. + * Gets the recommendation for a specific test result. If no recommendation is found, returns a + * default recommendation with no information available message. * * @param result the test result to find a recommendation for - * @return the matching property result recommendation or a default one + * @return the matching recommendation or a default recommendation if not found */ public PropertyResultRecommendation getPropertyResultRecommendation(TestResult result) { for (PropertyResultRecommendation r : propertyRecommendations) { @@ -318,7 +324,7 @@ public PropertyResultRecommendation getPropertyResultRecommendation(TestResult r } /** - * Gets the list of reference links. + * Gets the list of relevant links for more information. * * @return the list of links */ @@ -327,7 +333,7 @@ public List getLinks() { } /** - * Sets the reference links. + * Sets the list of relevant links for more information. * * @param links the list of links to set */ diff --git a/src/main/java/de/rub/nds/scanner/core/report/rating/Recommendations.java b/src/main/java/de/rub/nds/scanner/core/report/rating/Recommendations.java index c99392d..d5d3ba4 100644 --- a/src/main/java/de/rub/nds/scanner/core/report/rating/Recommendations.java +++ b/src/main/java/de/rub/nds/scanner/core/report/rating/Recommendations.java @@ -17,6 +17,11 @@ import java.io.Serializable; import java.util.List; +/** + * Container class for a collection of recommendations. This class manages multiple Recommendation + * instances and provides methods to retrieve specific recommendations based on analyzed properties + * and test results. + */ @XmlRootElement @XmlAccessorType(XmlAccessType.FIELD) public class Recommendations implements Serializable { @@ -29,9 +34,9 @@ public class Recommendations implements Serializable { private Recommendations() {} /** - * Constructs a Recommendations with the specified list of recommendations. + * Constructs a Recommendations container with the specified list of recommendations. * - * @param recommendations the list of recommendations + * @param recommendations the list of recommendations to manage */ public Recommendations(List recommendations) { this.recommendations = recommendations; @@ -47,7 +52,7 @@ public List getRecommendations() { } /** - * Sets the recommendations list. + * Sets the list of recommendations. * * @param recommendations the list of recommendations to set */ @@ -56,13 +61,13 @@ public void setRecommendations(List recommendations) { } /** - * Gets the property result recommendation for a specific property and test result. If no - * matching recommendation is found, returns a default recommendation with - * NO_RECOMMENDATION_FOUND messages. + * Gets the property result recommendation for a specific analyzed property and test result. If + * no matching recommendation is found, returns a default recommendation with "No recommendation + * found" messages. * - * @param property the analyzed property to find a recommendation for - * @param result the test result to find a recommendation for - * @return the matching property result recommendation or a default one + * @param property the analyzed property to search for + * @param result the test result to match + * @return the matching property result recommendation or a default if not found */ public PropertyResultRecommendation getPropertyRecommendation( AnalyzedProperty property, TestResult result) { @@ -79,11 +84,11 @@ public PropertyResultRecommendation getPropertyRecommendation( /** * Gets the recommendation for a specific analyzed property. If no matching recommendation is - * found, returns a default recommendation with the property's string representation as the - * short name. + * found, returns a new recommendation with the property's string representation as the short + * name. * - * @param property the analyzed property to find a recommendation for - * @return the matching recommendation or a default one + * @param property the analyzed property to search for + * @return the matching recommendation or a new basic recommendation if not found */ public Recommendation getRecommendation(AnalyzedProperty property) { for (Recommendation r : recommendations) { diff --git a/src/main/java/de/rub/nds/scanner/core/report/rating/RecommendationsIO.java b/src/main/java/de/rub/nds/scanner/core/report/rating/RecommendationsIO.java index e1cb997..10e9dc6 100644 --- a/src/main/java/de/rub/nds/scanner/core/report/rating/RecommendationsIO.java +++ b/src/main/java/de/rub/nds/scanner/core/report/rating/RecommendationsIO.java @@ -13,14 +13,19 @@ import jakarta.xml.bind.JAXBException; import java.util.Set; +/** + * Provides XML serialization and deserialization functionality for Recommendations objects. This + * class extends JaxbSerializer to handle the marshalling and unmarshalling of recommendation + * configurations to and from XML format. + */ public class RecommendationsIO extends JaxbSerializer { /** - * Constructs a RecommendationsIO with support for the specified AnalyzedProperty class. Creates - * a JAXB serializer configured to handle Recommendations and related classes. + * Constructs a RecommendationsIO serializer for the specified analyzed property class. This + * constructor initializes the JAXB context with all necessary classes for serialization. * - * @param analyzedPropertyClass the class of AnalyzedProperty to support in serialization - * @throws JAXBException if JAXB context creation fails + * @param analyzedPropertyClass the class of analyzed properties to include in the JAXB context + * @throws JAXBException if there is an error creating the JAXB context */ public RecommendationsIO(Class analyzedPropertyClass) throws JAXBException { diff --git a/src/main/java/de/rub/nds/scanner/core/report/rating/ScoreReport.java b/src/main/java/de/rub/nds/scanner/core/report/rating/ScoreReport.java index 2bd06d4..c0c6329 100644 --- a/src/main/java/de/rub/nds/scanner/core/report/rating/ScoreReport.java +++ b/src/main/java/de/rub/nds/scanner/core/report/rating/ScoreReport.java @@ -11,6 +11,11 @@ import de.rub.nds.scanner.core.probe.AnalyzedProperty; import java.util.Map; +/** + * Represents a score report containing the calculated rating score and the influencers that + * contributed to that score. This class provides a summary of how different property results + * affected the final rating. + */ public class ScoreReport { private final int score; @@ -25,11 +30,10 @@ private ScoreReport() { } /** - * Constructs a ScoreReport with the specified score and influencers. + * Constructs a ScoreReport with the specified score and map of influencers. * - * @param score the calculated score - * @param influencers the map of properties to their rating influencers that contributed to the - * score + * @param score the calculated rating score + * @param influencers a map of analyzed properties to their rating influencers */ public ScoreReport( int score, Map influencers) { @@ -38,18 +42,19 @@ public ScoreReport( } /** - * Gets the calculated score. + * Gets the calculated rating score. * - * @return the score value + * @return the rating score */ public int getScore() { return score; } /** - * Gets the map of properties to their rating influencers. + * Gets the map of influencers that contributed to the score. The map contains analyzed + * properties as keys and their corresponding rating influencers as values. * - * @return the map of analyzed properties to property result rating influencers + * @return the map of analyzed properties to rating influencers */ public Map getInfluencers() { return influencers; diff --git a/src/main/java/de/rub/nds/scanner/core/report/rating/SiteReportRater.java b/src/main/java/de/rub/nds/scanner/core/report/rating/SiteReportRater.java index 89621e2..9233dd4 100644 --- a/src/main/java/de/rub/nds/scanner/core/report/rating/SiteReportRater.java +++ b/src/main/java/de/rub/nds/scanner/core/report/rating/SiteReportRater.java @@ -16,6 +16,11 @@ import org.apache.logging.log4j.LogManager; import org.apache.logging.log4j.Logger; +/** + * Calculates rating scores for site reports based on property test results and configured rating + * influencers. This class evaluates how different property results affect the overall security + * rating of a site. + */ public class SiteReportRater { private static final Logger LOGGER = LogManager.getLogger(); @@ -25,10 +30,10 @@ public class SiteReportRater { private final Recommendations recommendations; /** - * Constructs a SiteReportRater with the specified influencers and recommendations. + * Constructs a SiteReportRater with the specified rating influencers and recommendations. * - * @param influencers the rating influencers to use for score calculation - * @param recommendations the recommendations to associate with this rater + * @param influencers the rating influencers configuration + * @param recommendations the recommendations configuration */ public SiteReportRater(RatingInfluencers influencers, Recommendations recommendations) { this.influencers = influencers; @@ -36,13 +41,12 @@ public SiteReportRater(RatingInfluencers influencers, Recommendations recommenda } /** - * Calculates and returns a score report based on the provided test results. The score is - * computed by applying the rating influencers to the test results, taking into account both - * positive and negative influences as well as score caps. + * Generates a score report based on the provided property test results. This method evaluates + * each property result against the configured rating influencers and calculates the overall + * score. * - * @param resultMap the map of analyzed properties to their test results - * @return a ScoreReport containing the calculated score and the influencers that contributed to - * it + * @param resultMap a map of analyzed properties to their test results + * @return a ScoreReport containing the calculated score and applied influencers */ public ScoreReport getScoreReport(Map resultMap) { LinkedHashMap ratingInfluencers = @@ -81,18 +85,18 @@ private static int computeScore( } /** - * Gets the recommendations associated with this rater. + * Gets the recommendations configuration used by this rater. * - * @return the recommendations + * @return the recommendations configuration */ public Recommendations getRecommendations() { return recommendations; } /** - * Gets the rating influencers used by this rater. + * Gets the rating influencers configuration used by this rater. * - * @return the rating influencers + * @return the rating influencers configuration */ public RatingInfluencers getRatingInfluencers() { return influencers;