From 81124c72cbc6fcccc00c87a3e9b188bdc41f183d Mon Sep 17 00:00:00 2001 From: Fabrizio Fadigati Date: Tue, 13 Jan 2026 21:13:18 +0100 Subject: [PATCH] Refine README examples and added SARIF output documentation Updated examples and commands in README for clarity and structure. --- README.md | 264 ++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 256 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 31db225..78b670a 100644 --- a/README.md +++ b/README.md @@ -131,34 +131,282 @@ The primary command is `scan`, which can target a local file, a directory, or ev pyspector scan [PATH or --url REPO_URL] [OPTIONS] ``` -### Examples: +### Examples -* **Scan a single file** +#### Scan a single file + +##### Command ```bash pyspector scan project/main.py ``` +##### Sample Output +``` +[*] Starting PySpector scan on 'project/main.py'... +[*] Successfully parsed 1 Python files +[*] Starting analysis with 240 rules +[+] Found 1 files to scan +[+] Found 0 issues from config analysis +[+] 1 issues from Python AST analysis +[*] Building call graph from 1 files +[*] Processing file: main.py +[+] Found 0 total functions +[*] Starting taint analysis with 0 functions +[+] Taint sources: 1, sinks: 1 +[+] Found 0 tainted variables +[+] Found 0 issues from taint analysis +[*] Total issues after deduplication: 1 + +[+] Rule ID: PY001 + Description: Use of 'eval()' is highly dangerous. + Severity: HIGH + File: project/main.py:1 + Code: `eval("a=5 print(a)")` + +[*] Scan finished in 0.07 seconds. Found 1 issues. +``` + +#### Scan a local directory and save the report as HTML -* **Scan a local directory and save the report as HTML:** +##### Command ```bash pyspector scan /path/to/your/project -o report.html -f html ``` -* **Scan a public GitHub repository:** +##### Sample HTML report +```html + +PySpector Scan Report + +

PySpector Scan Report

+

Found 1 issues.

+ + + + + + + + + + + + + + + +
FileLineSeverityDescriptionCode
/path/to/your/project/file.py1Severity.HighUse of 'eval()' is highly dangerous.
eval("a=5 print(a)")
+ + +``` + +#### Scan a local directory and save the report as JSON + +##### Command ```bash -pyspector scan --url https://github.com/username/repo.git +pyspector scan /path/to/your/project -o report.json -f json ``` -### Scan for AI and LLM Vulnerabilities +##### Sample JSON report +```json +{ + "summary": { + "issue_count": 1 + }, + "issues": [ + { + "rule_id": "PY001", + "description": "Use of 'eval()' is highly dangerous.", + "file_path": "/path/to/your/project/file.py", + "line_number": 1, + "code": "eval(\"a=5 print(a)\")", + "severity": "High", + "remediation": "Avoid 'eval()'. Use safer alternatives like 'ast.literal_eval' for data parsing." + } + ] +} +``` -image +#### Scan a local directory and save the report as SARIF (Static Analysis Results Interchange Format) +PySpector currently supports exporting analysis results in SARIF version 2.1.0.
+The official JSON schema for this version is available at this [link](https://www.schemastore.org/schemas/json/sarif-2.1.0-rtm.5.json) -* **Use the `--ai` flag to enable a specialized ruleset, for projects using Large Language Models:** +##### Command +```bash +pyspector scan /path/to/your/project -o report.sarif -f sarif +``` +##### Sample SARIF report +```json +{ + "runs": [ + { + "tool": { + "driver": { + "id": "pyspector", + "default_configuration": null, + "deprecated_guids": null, + "deprecated_ids": null, + "deprecated_names": null, + "full_description": null, + "guid": null, + "help": null, + "help_uri": null, + "message_strings": null, + "name": "PySpector", + "properties": null, + "relationships": null, + "short_description": null, + "rules": [ + { + "id": "PY001", + "default_configuration": null, + "deprecated_guids": null, + "deprecated_ids": null, + "deprecated_names": null, + "full_description": null, + "guid": null, + "help": null, + "help_uri": null, + "message_strings": null, + "name": "Use of 'eval()' is highly dangerous.", + "properties": null, + "relationships": null, + "short_description": null + } + ] + }, + "extensions": null, + "properties": null + }, + "addresses": null, + "artifacts": null, + "automation_details": null, + "baseline_guid": null, + "column_kind": null, + "conversion": null, + "default_encoding": null, + "default_source_language": null, + "external_property_file_references": null, + "graphs": null, + "invocations": null, + "language": "en-US", + "logical_locations": null, + "newline_sequences": [ + "\r\n", + "\n" + ], + "original_uri_base_ids": null, + "policies": null, + "properties": null, + "redaction_tokens": null, + "results": [ + { + "message": { + "text": "Use of 'eval()' is highly dangerous." + }, + "analysis_target": null, + "attachments": null, + "baseline_state": null, + "code_flows": null, + "correlation_guid": null, + "fingerprints": null, + "fixes": null, + "graph_traversals": null, + "graphs": null, + "guid": null, + "hosted_viewer_uri": null, + "kind": "fail", + "level": "warning", + "locations": [ + { + "annotations": null, + "id": -1, + "logical_locations": null, + "message": null, + "physical_location": { + "address": null, + "artifact_location": { + "description": null, + "index": -1, + "properties": null, + "uri": "/path/to/your/project/file.py", + "uri_base_id": null + }, + "context_region": null, + "properties": null, + "region": { + "byte_length": null, + "byte_offset": -1, + "char_length": null, + "char_offset": -1, + "end_column": null, + "end_line": null, + "message": null, + "properties": null, + "snippet": null, + "source_language": null, + "start_column": null, + "start_line": 1 + } + }, + "properties": null, + "relationships": null + } + ], + "occurrence_count": null, + "partial_fingerprints": null, + "properties": null, + "provenance": null, + "rank": -1.0, + "related_locations": null, + "rule": null, + "rule_id": "PY001", + "rule_index": -1, + "stacks": null, + "suppressions": null, + "taxa": null, + "web_request": null, + "web_response": null, + "work_item_uris": null + } + ], + "run_aggregates": null, + "special_locations": null, + "taxonomies": null, + "thread_flow_locations": null, + "translations": null, + "version_control_provenance": null, + "web_requests": null, + "web_responses": null + } + ], + "version": "2.1.0", + "schema_uri": "https://schemastore.azurewebsites.net/schemas/json/sarif-2.1.0-rtm.5.json", + "inline_external_properties": null, + "properties": null +} +``` + +#### Scan a public GitHub repository +##### Command +```bash +pyspector scan --url https://github.com/username/repo.git +``` + +#### Scan for AI and LLM Vulnerabilities + +Use the `--ai` flag to enable a specialized ruleset, for projects using Large Language Models. + +##### Command ```bash pyspector scan /path/to/your/project --ai ``` +##### Sample output +image + + ## Plugin System (NEW FEATURE🚀) image PySpector ships with an extensible plugin architecture that lets you post-process findings, generate custom artefacts, or orchestrate follow-up actions after every scan. Plugins run in-process once the Rust core returns the final issue list, so they see exactly the same normalized data that drives the built-in reports.