0
# Output Formatting
1

2
Comprehensive output formatting system supporting multiple formats including JSON, SARIF, text, and XML for integration with various tools and workflows.
3

4
## Capabilities
5

6
### Output Handler
7

8
Main class for managing output generation and formatting.
9

10
```python { .api }
11
class OutputHandler:
12
    """
13
    Handles output generation and formatting for scan results.
14
    
15
    Manages different output formats and provides unified interface
16
    for writing scan results to various destinations.
17
    """
18
    def __init__(self, output_settings): ...
19
    
20
    def handle_results(self, results, errors, stats): ...
21
    def write_to_file(self, content, file_path): ...
22
    def write_to_stdout(self, content): ...
23
    def format_results(self, results, formatter): ...
24

25
class OutputSettings:
26
    """
27
    Configuration for output formatting behavior.
28
    
29
    Attributes:
30
    - output_format (OutputFormat): Format for output (JSON, SARIF, TEXT, etc.)
31
    - output_file (str): File path for output, None for stdout
32
    - verbose (bool): Include verbose information
33
    - debug (bool): Include debug information
34
    - show_supported_languages (bool): Show supported languages
35
    - timeout (int): Timeout for rule execution
36
    - max_target_bytes (int): Maximum target file size
37
    """
38
    def __init__(self, **kwargs): ...
39

40
class NormalizedOutputSettings:
41
    """
42
    Normalized output settings with validated parameters.
43
    
44
    Processed version of OutputSettings with defaults applied
45
    and validation performed.
46
    """
47
    def __init__(self, output_settings): ...
48
```
49

50
### Formatter Classes
51

52
Specific formatters for different output formats.
53

54
```python { .api }
55
class JsonFormatter:
56
    """
57
    Formats scan results as JSON for machine processing.
58
    
59
    Produces structured JSON output compatible with semgrep JSON schema.
60
    """
61
    def format(self, results, errors, **kwargs): ...
62
    def format_rule_match(self, match): ...
63

64
class SarifFormatter:
65
    """
66
    Formats scan results as SARIF for security tool integration.
67
    
68
    SARIF (Static Analysis Results Interchange Format) is a standard
69
    format for static analysis tools.
70
    """
71
    def format(self, results, errors, **kwargs): ...
72
    def create_sarif_run(self, results, rules): ...
73
    def create_sarif_result(self, match): ...
74

75
class TextFormatter:
76
    """
77
    Formats scan results as human-readable text.
78
    
79
    Provides colored terminal output with file locations,
80
    code snippets, and rule information.
81
    """
82
    def format(self, results, errors, **kwargs): ...
83
    def format_match_text(self, match): ...
84
    def colorize_output(self, text, color): ...
85

86
class JunitXmlFormatter:
87
    """
88
    Formats scan results as JUnit XML for CI integration.
89
    
90
    Compatible with CI systems that consume JUnit test results.
91
    """
92
    def format(self, results, errors, **kwargs): ...
93
    def create_test_case(self, match): ...
94

95
class EmacsFormatter:
96
    """
97
    Formats scan results for Emacs editor integration.
98
    
99
    Uses Emacs compilation mode format for easy navigation
100
    to findings within the editor.
101
    """
102
    def format(self, results, errors, **kwargs): ...
103

104
class VimFormatter:
105
    """
106
    Formats scan results for Vim editor integration.
107
    
108
    Uses Vim quickfix format for jumping to findings
109
    within the editor.
110
    """
111
    def format(self, results, errors, **kwargs): ...
112

113
class GitlabSastFormatter:
114
    """
115
    Formats scan results for GitLab SAST integration.
116
    
117
    Produces GitLab SAST report format for security
118
    dashboard integration.
119
    """
120
    def format(self, results, errors, **kwargs): ...
121

122
class GitlabSecretsFormatter:
123
    """
124
    Formats scan results for GitLab Secrets detection.
125
    
126
    Produces GitLab Secrets report format for credential
127
    scanning integration.
128
    """
129
    def format(self, results, errors, **kwargs): ...
130
```
131

132
## Constants
133

134
### Output Format Types
135

136
```python { .api }
137
class OutputFormat:
138
    """
139
    Enumeration of supported output formats.
140
    
141
    Values:
142
    - TEXT: Human-readable text output with colors
143
    - JSON: Structured JSON format
144
    - SARIF: SARIF format for security tools
145
    - JUNIT_XML: JUnit XML for CI integration
146
    - EMACS: Emacs compilation mode format
147
    - VIM: Vim quickfix format
148
    - GITLAB_SAST: GitLab SAST report format
149
    - GITLAB_SECRETS: GitLab Secrets report format
150
    """
151
    TEXT = "text"
152
    JSON = "json"
153
    SARIF = "sarif"
154
    JUNIT_XML = "junit-xml"
155
    EMACS = "emacs"
156
    VIM = "vim"
157
    GITLAB_SAST = "gitlab-sast"
158
    GITLAB_SECRETS = "gitlab-secrets"
159

160
FORMATTERS = {
161
    OutputFormat.TEXT: TextFormatter,
162
    OutputFormat.JSON: JsonFormatter,
163
    OutputFormat.SARIF: SarifFormatter,
164
    OutputFormat.JUNIT_XML: JunitXmlFormatter,
165
    OutputFormat.EMACS: EmacsFormatter,
166
    OutputFormat.VIM: VimFormatter,
167
    OutputFormat.GITLAB_SAST: GitlabSastFormatter,
168
    OutputFormat.GITLAB_SECRETS: GitlabSecretsFormatter,
169
}
170

171
DEFAULT_SHOWN_SEVERITIES = {"ERROR", "WARNING"}
172
```
173

174
## Usage Examples
175

176
### Basic Output Formatting
177

178
```python
179
from semgrep.output import OutputHandler, OutputSettings, OutputFormat
180
from semgrep.formatter.json import JsonFormatter
181

182
# Configure JSON output to file
183
settings = OutputSettings(
184
    output_format=OutputFormat.JSON,
185
    output_file="results.json",
186
    verbose=True
187
)
188

189
# Create output handler
190
handler = OutputHandler(settings)
191

192
# Format and write results (assuming we have scan results)
193
handler.handle_results(results, errors, stats)
194
```
195

196
### Custom Formatting
197

198
```python
199
from semgrep.formatter.sarif import SarifFormatter
200

201
# Create SARIF formatter
202
formatter = SarifFormatter()
203

204
# Format results manually
205
sarif_output = formatter.format(
206
    results=scan_results,
207
    errors=scan_errors,
208
    rules=config.rules
209
)
210

211
# Write to file
212
with open("results.sarif", "w") as f:
213
    f.write(sarif_output)
214
```
215

216
### Multiple Output Formats
217

218
```python
219
# Generate multiple output formats
220
formatters = {
221
    "json": JsonFormatter(),
222
    "sarif": SarifFormatter(), 
223
    "text": TextFormatter()
224
}
225

226
for format_name, formatter in formatters.items():
227
    output = formatter.format(results, errors)
228
    
229
    with open(f"results.{format_name}", "w") as f:
230
        f.write(output)
231
```