Disclaimer: This SAST tool " + PYTHON_CODE_AUDIT_TEXT + " provides a powerful, automatic security analysis for Python source code. However, it's not a substitute for human review in combination with business knowledge. Undetected vulnerabilities may still exist.
" ) NOSEC_WARNING = "INFO: The --nosec flag is active. Security findings with in-line suppressions will be excluded from the report.
" SIMPLE_CSS_FILE = files("codeaudit") / "simple.css" DEFAULT_OUTPUT_FILE = "codeaudit-report.html" def overview_report(directory, filename=DEFAULT_OUTPUT_FILE): """Generates an overview report of code complexity and security indicators. This function analyzes a Python project to produce a high-level overview of complexity and security-related metrics. The input may be either: - A local directory containing Python source files - The name of a package hosted on PyPI.org So: codeaudit overview👉 To perform a SAST scan on the source code, run:
codeaudit filescan {package_name}Codeaudit overview scan of package: {package_name}
" output += f"Version:{release}
" else: output += f"Overview for the directory: {directory}
" output += f"Based on the maximum found complexity in a source file: Security concern rate is ❌ HIGH." else: output += "
Based on the maximum found complexity in a source file: Security concern rate is ✅ LOW." security_based_on_loc = overview_df.loc[0, "Number_Of_Lines"] if security_based_on_loc > 2000: output += "
Based on the total Lines of Code (LoC) : Security concern rate is ❌ HIGH." else: output += "
Based on the total Lines of Code (LoC) : Security concern rate is ✅ LOW."
output += "
"
## Module overview
modules_discovered = get_all_modules(directory)
if clean_up:
tmp_handle.cleanup() # Clean up tmp directory if overview is created directly from PyPI package
output += "View all discovered modules.
"
output += display_found_modules(modules_discovered)
output += "
💬 Advice:
" if advice is not None and advice != "": output += advice else: output += f'👉 To perform a SAST scan on the source code, run:
codeaudit filescan {directory}Used Python Standard libraries:
" output += ( "Imported libraries (packages):
" output += ( "" + f"Location of the file: {input_path}
" if nosec: html_output += NOSEC_WARNING html_output += file_report_html html_output += secrets_report_html html_output += "⚠️ External Egress Risk: Detected outbound connection logic or API keys that may facilitate data egress.
" output += "✅ No Logic for connecting to remote services found. Risk of data exfiltration to external systems is low.
" return output def pylint_reporting(result): """ Creates a pandas DataFrame of privacy findings with columns: 'line', 'found', and 'code'. - Escapes HTML for safe rendering - Converts newlines to block
- Optimized for performance (fewer lookups, reusable template)
"""
rows = []
append_row = rows.append # local reference (faster in loops)
# Predefine template (faster than rebuilding strings each loop)
template = '{}
'
# Safely get dict
file_checks = result.get("file_privacy_check") or {}
for item in file_checks.values():
entries = item.get("privacy_check_result", [])
for entry in entries:
code = entry.get("code", "")
lineno = entry.get("lineno")
matched = entry.get("matched")
# Escape HTML and replace newlines (done once per entry)
escaped_code = html.escape(code).replace("\n", "
")
# Format HTML block (faster than f-string in tight loops)
code_html = template.format(escaped_code)
append_row(
{
"line": lineno,
"found": matched,
"code": code_html,
}
)
return pd.DataFrame(rows, columns=["line", "found", "code"])
def single_file_report(filename, scan_output):
"""Function to DRY for a codescan when used for single for CLI or within a directory scan"""
data = scan_output["result"]
df = pd.DataFrame(
[(key, lineno) for key, linenos in data.items() for lineno in linenos],
columns=["validation", "line"],
)
number_of_issues = len(df)
df["severity"] = None
df["info"] = None
for error_str in data:
severity, info_text = get_info_on_test(error_str)
matching_rows = df[df["validation"] == error_str]
if not matching_rows.empty:
# Update all matching rows
df.loc[matching_rows.index, ["severity", "info"]] = [severity, info_text]
df["code"] = None
filename_location = scan_output["file_location"]
for idx, row in df.iterrows():
line_num = row["line"]
df.at[idx, "code"] = _collect_issue_lines(filename_location, line_num)
df["code"] = df["code"].str.replace(
r"\n", "
", regex=True
) # to convert \n to \\n for display
df["validation"] = df["validation"].apply(
replace_second_dot
) # Make the validation column smaller - this is the simplest way! without using styling options from Pandas!
df = df[
["line", "validation", "severity", "info", "code"]
] # reorder the columns before converting to html
df = df.sort_values(by="line") # sort by line number
if number_of_issues > 0:
# output = f'⚠️ {number_of_issues} potential security issues found!
'
output = f'⚠️ {number_of_issues} potential security issue{"s" if number_of_issues != 1 else ""} found!
'
output += ""
output += "View identified security weaknesses.
"
output += df.to_html(escape=False, index=False)
output += ""
output += "
"
else:
output = "" # No weaknesses found, no message, since privacy breaches may be present.
file_overview = overview_per_file(filename)
df_overview = pd.DataFrame([file_overview])
output += ""
output += (
f"View detailed analysis of security relevant file details.
"
)
output += df_overview.to_html(escape=True, index=False)
output += ""
output += "
"
output += ""
output += "View used modules in this file.
"
modules_found = get_imported_modules_by_file(filename)
output += display_found_modules(modules_found)
output += f'To check for reported vulnerabilities in external modules used by this file, use the command:
codeaudit modulescan {filename}
'
output += ""
return output
def directory_scan_report(
directory_to_scan,
nosec_flag,
filename=DEFAULT_OUTPUT_FILE,
package_name=None,
release=None,
):
"""Reports potential security issues for all Python files found in a directory.
This function performs security validations on all files found in a specified directory.
The result is written to a HTML report.
You can specify the name and directory for the generated HTML report.
Parameters:
directory_to_scan (str) : The full path to the Python source files to be scanned. Can be present in temp directory.
filename (str, optional): The name of the HTML file to save the report to.
Defaults to `DEFAULT_OUTPUT_FILE`.
Returns:
None - A HTML report is written as output
"""
# Check if the provided path is a valid directory
if not os.path.isdir(directory_to_scan):
print(f"Error: '{directory_to_scan}' is not a valid directory.")
exit(1)
collection_ok_files = [] # create a collection of files with no issues found
output = "Python Code Audit Report
"
files_to_check = collect_python_source_files(directory_to_scan)
output += "Directory scan report
"
name_of_package = get_filename_from_path(directory_to_scan)
if package_name is not None:
# Use real package name and retrieved release info
output += f"Below the result of the Codeaudit scan of (Package name - Release):
"
output += f" {package_name} - {release}
"
else:
output += f"Below the result of the Codeaudit scan of the directory: {name_of_package}
"
output += f"Total Python files found: {len(files_to_check)}
"
if nosec_flag:
output += NOSEC_WARNING
number_of_files = len(files_to_check)
print(f"Number of files that are checked for security issues:{number_of_files}")
printProgressBar(
0, number_of_files, prefix="Progress:", suffix="Complete", length=50
)
for i, file_to_scan in enumerate(files_to_check):
printProgressBar(
i + 1, number_of_files, prefix="Progress:", suffix="Complete", length=50
)
if not nosec_flag: # no filtering on reviewed items with markers in code
scan_output = perform_validations(
file_to_scan
) # scans for weaknesses in the file
else:
unfiltered_scan_output = perform_validations(
file_to_scan
) # scans for weaknesses in the file
scan_output = filter_sast_results(unfiltered_scan_output)
spy_output = data_egress_scan(file_to_scan) # scans for secrets in the file
data = scan_output["result"]
if data or has_privacy_findings(spy_output):
file_report_html = single_file_report(file_to_scan, scan_output)
name_of_file = get_filename_from_path(file_to_scan)
output += f"Security scan: {name_of_file}
"
if package_name is None:
output += "" + f"Location of the file: {file_to_scan}
"
output += file_report_html
secrets_report_html = secrets_report(spy_output)
output += secrets_report_html
else:
file_name_with_no_issue = get_filename_from_path(file_to_scan)
collection_ok_files.append(
{"filename": file_name_with_no_issue, "directory": file_to_scan}
)
output += "Files in directory with no security issues
"
output += f"✅ Total Python files without detected security issues: {len(collection_ok_files)}
"
output += "The Python files with no security issues detected by codeaudit are:
"
output += dict_list_to_html_table(collection_ok_files)
output += "
"
if package_name is not None:
output += f"
Note:Since this check is done on a package on PyPI.org, the temporary local directories are deleted. To examine the package in detail, you should download the sources locally and run the command:codeaudit filescan again.
"
output += "Disclaimer:This scan only evaluates Python files. Please note that security vulnerabilities may also exist in other files associated with the Python module.
"
output += DISCLAIMER_TEXT
create_htmlfile(output, filename)
def report_module_information(inputfile, reportname=DEFAULT_OUTPUT_FILE):
"""
Generate a report on known vulnerabilities in Python modules and packages.
This function analyzes a single Python file to identify imported
external modules and checks those modules against the OSV vulnerability
database. The collected results are written to a static HTML report.
If the input refers to a valid PyPI package name instead of a local Python
file, the function generates a vulnerability report directly for that
package.
While processing modules, progress information is printed to standard
output.
Example:
Generate a module vulnerability report for a Python file::
codeaudit modulescan | [yourreportname.html]
codeaudit modulescan mypythonfile.py
Args:
inputfile (str): Path to a Python source file (*.py) to analyze, or the
name of a package available on PyPI.
reportname (str, optional): Name (and optional path) of the HTML file to
write the vulnerability report to. The filename should use the
``.html`` extension. Defaults to ``DEFAULT_OUTPUT_FILE``.
Returns:
None: The function writes a static HTML report to disk.
Raises:
SystemExit: If the input is not a valid Python file or a valid PyPI
package. File parsing and I/O errors are reported via standard
output before exiting.
"""
html_output = "Python Code Audit Report
"
file_path = Path(inputfile)
if file_path.is_dir():
print(
"codeaudit modulescan only works on single python files (*.py) or packages present on PyPI.org"
)
print(
"See codeaudit modulescan -h or check the manual https://codeaudit.nocomplexity.com"
)
exit(1)
elif (
file_path.suffix == ".py" and file_path.is_file() and is_ast_parsable(inputfile)
):
source = read_in_source_file(inputfile)
used_modules = get_imported_modules(source)
# Initial call to print 0% progress
external_modules = used_modules["imported_modules"]
l = len(external_modules)
printProgressBar(0, l, prefix="Progress:", suffix="Complete", length=50)
html_output += f"Module scan report
"
html_output += f"Security information for file: {inputfile}
"
html_output += f"Total Dependencies Scanned: {l}
"
if external_modules:
html_output += ""
html_output += "View scanned module dependencies(imported packages).
"
html_output += (
"\n"
+ "\n".join(f" - {module}
" for module in external_modules)
+ "\n
"
)
html_output += ""
else:
html_output += "✅ No external modules found!"
# Now vuln info per external module
if external_modules:
html_output += "
Vulnerability information for detected modules
"
for i, module in enumerate(external_modules): # sorted for nicer report
printProgressBar(i + 1, l, prefix="Progress:", suffix="Complete", length=50)
html_output += module_vulnerability_check(module) + "
"
html_output += f'
💡 To check for security weaknesses in this package, use the command:
codeaudit filescan {inputfile}
'
html_output += "
" + DISCLAIMER_TEXT
create_htmlfile(html_output, reportname)
elif get_pypi_download_info(inputfile):
package_name = inputfile # The input variable is now equal to the package name
html_output += f"Package scan report for known vulnerabilities
"
html_output += module_vulnerability_check(package_name)
html_output += f'
💡 To check for security weaknesses in this package, use the command:
codeaudit filescan {package_name}
'
html_output += "
" + DISCLAIMER_TEXT
create_htmlfile(html_output, reportname)
else:
# File is NOT a valid Python file, or package does not exist on PyPI.
print(
f"Error: '{inputfile}' isn't a valid Python file(*.py), or a valid package on PyPI.org."
)
exit(1)
def module_vulnerability_check(module):
"""
Build the HTML fragment for the module vulnerability section of a code audit
module scan report.
The function checks whether vulnerability information is available for the
given Python package/module and returns an HTML snippet accordingly:
- If no vulnerabilities are found, a success message is rendered.
- If vulnerabilities are found, a collapsible HTML section is
generated containing the formatted vulnerability data.
Args:
module (str): Name of the Python package/module to check.
Returns:
str: HTML string representing the vulnerability scan result for the module.
"""
output = ""
vuln_info = check_module_vulnerability(module)
if not vuln_info:
# here SAST scan for package? - not needed (now)- do a filescan on Python package manually - dependency trees can be deep and for complex package are never Python only.
output += f"✅ No known vulnerabilities found for package: {module}.
"
else:
output += ""
output += f"⚠️ View vulnerability information for package {module}.
"
output += json_to_html(vuln_info)
output += ""
return output
def create_htmlfile(html_input, outputfile):
"""Creates a clean html file based on html input given"""
output_path = Path(outputfile).expanduser().resolve()
# Validate output directory (CLI-friendly)
if not output_path.parent.is_dir():
print(
f"Error: output directory does not exist:\n {output_path.parent}",
file=sys.stderr,
)
sys.exit(1)
# Read CSS so it is included in the reporting HTML file
css_content = Path(SIMPLE_CSS_FILE).read_text(encoding="utf-8")
# Start building the HTML
output = ''
output += ''
output += "Python_Code_Audit_SecurityReport "
output += f""
output += ''
output += ''
output += ''
output += ""
output += ''
output += html_input
now = datetime.datetime.now()
timestamp_str = now.strftime("%Y-%m-%d %H:%M")
output += (
f"This Python security report was created on: {timestamp_str} "
f"with {PYTHON_CODE_AUDIT_TEXT} version {CA_VERSION}
"
)
output += "
"
output += ""
output += ""
output += ""
# Write the HTML file
output_path.write_text(output, encoding="utf-8")
print("\n=====================================================================")
print(
"Code Audit report file created!\n"
"Paste the line below directly into your browser bar:\n"
f"\t{output_path.as_uri()}\n"
)
print("=====================================================================\n")
def extract_altair_html(plot_html):
match = re.search(r"]*>(.*?)