| Name | py-secscan JSON |
| Version |
0.1.1
JSON |
| download |
| home_page | None |
| Summary | PySecScan is the tool that allows you to perform security scans in your Python project through a simple YAML configuration. |
| upload_time | 2025-02-16 17:58:20 |
| maintainer | None |
| docs_url | None |
| author | FabrizioCafolla |
| requires_python | >=3.12 |
| license | None |
| keywords |
py-secscan
sast
requirements
packaging
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# PY SecScan
[](https://pypi.python.org/pypi/py-secscan)
[](https://pypi.python.org/pypi/py-secscan)
[](https://pypi.python.org/pypi/py-secscan)
[](https://github.com/astral-sh/uv/actions)
[](https://github.com/astral-sh/uv)
PySecScan is a lightweight and easy-to-use security scanning tool for Python projects. With a simple YAML configuration, it seamlessly integrates into any workflow, regardless of the framework or dependencies used. PySecScan automates security checks, linting, and SBOM generation, ensuring a proactive approach to code security with minimal setup.
## Table of Contents 📚
- [PY SecScan](#py-secscan)
- [Table of Contents 📚](#table-of-contents-)
- [Guide](#guide)
- [Installation](#installation)
- [Getting start](#getting-start)
- [CLI](#cli)
- [GitHub Actions](#github-actions)
- [Pre-commit](#pre-commit)
- [How It Works](#how-it-works)
- [Configuration Schema](#configuration-schema)
- [Virtual Environment](#virtual-environment)
- [Subprocess](#subprocess)
- [Usage](#usage)
- [Enable `sbom_vulnerabilities`](#enable-sbom_vulnerabilities)
- [View SBOM file](#view-sbom-file)
- [Develop](#develop)
- [Setup with Nix environment](#setup-with-nix-environment)
- [Setup in Local Environment](#setup-in-local-environment)
- [Tests](#tests)
## Guide
### Installation
1. Ensure you have Python 3.12 or higher installed on your system. You can download it from the [official Python website](https://www.python.org/downloads/).
2. Install PySecScan using pip or uv:
```bash
pip install py-secscan
# Or using uv
uv add --dev py-secscan
```
### Getting start
1. Create a sample Python project and navigate to its root directory.
2. Define the `.py-secscan.conf.yml` configuration file like this:
```yaml
version: "1"
packages:
- command_name: "echo"
command_args: ["test"]
```
3. Run the security scan:
```bash
py-secscan scan
```
4. Output
```plaintext
[INFO] Subprocess command: <path>/.venv/bin/python -m ensurepip --upgrade
[INFO] Subprocess command: <path>/.venv/bin/python -m pip install -r <path>/.py-secscan/requirements.txt
[INFO] Execute builtins packages
[INFO] Executing package ruff
[INFO] Subprocess command: ruff check --fix
All checks passed!
[INFO] Package ruff completed
[INFO] Executing package cyclonedx-py
[INFO] Subprocess command: cyclonedx-py environment --outfile sbom.json <path>/.venv
[INFO] Package cyclonedx-py completed
[WARNING] python package is disabled
[INFO] {'logger_filepath': '<path>/.py-secscan/logs/py-secscan.2025-02-12.log', 'status': {'ruff': 'completed', 'cyclonedx-py': 'completed', 'python': 'disabled'}}
[INFO] Execute packages
[INFO] Executing package echo
[INFO] Subprocess command: echo test
test
[INFO] Package echo completed
[INFO] {'logger_filepath': '<path>/.py-secscan/logs/py-secscan.2025-02-12.log', 'status': {'ruff': 'completed', 'cyclonedx-py': 'completed', 'python': 'disabled', 'echo': 'completed'}}
```
### CLI
The `py-secscan` command currently has the following options:
**`scan`**: Loads the `.py-secscan.conf.yml` configuration and executes the defined commands. The security scan is, of course, proportional to what you define. By default, a linting check is performed, and the SBOM file is generated.
**`view`**: Launches a web page based on Streamlit to visualize the SBOM and any detected vulnerabilities (if `builtins.sbom_vulnerabilities` is enabled). To use this command, you must install streamlit manually or via `pip install 'py-secscan[view]'` (recommended choice).
> You can increase the verbosity level using the `-v` and `-vv` options.
### GitHub Actions
> IN PROGRESS
### Pre-commit
> IN PROGRESS
## How It Works
```mermaid
flowchart TD
A(["Your Python Project"]) -- define ---> C[".py-secsca.conf.yml"]
PySecScan(["$ py-secscan scan"]) -- run ---> Process
Process -. load ..-> C
Process -- check/setup --> Env
Process == exec ===> Subprocess["Subprocess
(builtins / packages)"]
Subprocess == stdout/stderr ===> Output
Subprocess -. save: FAILED or COMPLETED ..-> ExecutionStatus["Execution Status"]
Process -. save: RUNNING or DISABLED ..-> ExecutionStatus
Subprocess -. use ..-> Env["Virtual Environment"]
Output == next: subprocess ==> Process
```
The functionality of PySecScan is simple: using the `.py-secscan.conf.yml` configuration file, you can define the security scanning strategy for your project.
**Builtins**:
By default, the `py-secscan scan` command performs a project check using `ruff` and creates the SBOM file using `cyclonedx`. Additionally, you can enable `sbom_vulnerabilities` to scan each package listed in `sbom.json` using the OSV API.
**Packages**:
Once the builtins are executed, the scan retrieves the defined `packages` and runs them one by one (installing them in the virtual environment first if defined). **It is recommended to execute only Python packages related to security checks**, but any type of binary can be executed as it runs as a subprocess (be mindful of `FORBIDDEN_OPERATORS`, which prevent the execution of certain commands).
\* Package installation is limited to Python packages available on PyPI.
### Configuration Schema
The `.py-secscan.conf.yml` configuration file must contain at least the `version` key and is structured into several optional sections to customize `py-secscan`'s behavior. For more details view [jsonschema version 1](py_secscan/scan/parser/v1/pysecscan.schema.json)
**1. Version**:
- `version` (*required*): A string that defines the parser version to use. Currently supported versions: `1`.
**2. Options**:
- `debug` (*default: false | optional*): Enables debug mode.
- `env` (*default: {} | optional*): Dictionary of environment variables.
- `pysecscan_dirpath` (*default: ".py-secscan" | optional*): Path to the PySecScan directory.
- `venv_dirpath` (*default: ".venv" | optional*): Path to the virtual environment directory.
- `enabled` (*default: true | optional*): Enables/disables security checks.
- `disable_builtins` (*default: false | optional*): Disables all built-in commands.
- `disable_venv_check` (*default: false | optional*): Disables the virtual environment check, allowing execution in a non-virtual environment.
- `disable_venv_creation` (*default: false | optional*): Disables automatic virtual environment creation.
- `disable_venv_install` (*default: false | optional*): Disables the installation of packages defined in the `packages` directive in the virtual environment.
- `additional_forbidden_commands` (*default: [] | optional*): Additional list of forbidden commands that will be blocked.
**3. Packages**:
List of commands to execute.
- `command_name` (*required*): Name of the command to execute.
- `command_args` (*default: [] | optional*): List of string arguments to pass to the command.
- `install` (*default: {} | optional*):
- `enabled` (*default: false | optional*): If true, the package will be installed automatically.
- `package_name` (*default: "" | optional*): Used to define the package name for installation via `pip install <package_name>==<version>`. If not defined, it defaults to `command_name`.
- `version` (*default: "latest" | optional*): Package version.
- `extras` (*default: [] | optional*): Extra installation options.
- `enabled`: If false, the package will not be executed and will be marked as `DISABLED`.
- `on_error_continue`: If true, errors will not stop the execution of subsequent packages.
**4. Builtins**:
Builtins are predefined packages that can be enabled/disabled or configured differently at any time.
The `ruff` builtin automatically performs an initial linting check on the entire project.
- `ruff`:
- `command_name`: "ruff"
- `command_args`: ["check --fix"]
- `enabled`: True
- `on_error_continue`: False
The `cyclonedx` builtin automatically scans the virtual environment and generates an SBOM file containing all dependencies.
- `cyclonedx`:
- `command_name`: "cyclonedx-py"
- `command_args`: [
"environment --outfile sbom.json <venv_path>"
]
- `enabled`: True
- `on_error_continue`: False
The `sbom_vulnerabilities` builtin, when enabled, scans for vulnerabilities in each dependency listed in the SBOM file using the [OSV](https://osv.dev/) API.
- `sbom_vulnerabilities`:
- `command_name`: "python -m py_secscan.modules.builtins.sbom_vulnerabilities"
- `command_args`: ["sbom.json sbom_vulnerabilities.json"]
- `enabled`: False
- `on_error_continue`: True
### Virtual Environment
A virtual environment (venv) must be present at the specified path and activated before executing the `py-secscan scan` command. Before execution, a check ensures that the correct venv is being used (default: `<project-path>/.venv`).
Once verified, all defined packages with `install.enabled: true` are installed. A `.py-secscan/requirements.txt` file is created, containing the list of packages installed at runtime by PySecScan.
This allows you to destroy the venv without worrying about losing installed packages since they will always be reinstalled based on the configuration.
> ⚠️ WARNING: Disabling the virtual environment check is possible but not recommended, as it could lead to installing packages globally. This should be used only in CI/CD contexts by setting `options.disable_venv_check` to `true`.
### Subprocess
As shown in the diagram, every execution of a `builtin` or `package` is a Python subprocess. The executed command is sanitized and checked to prevent harmful commands. Each execution status is recorded as `RUNNING`, `COMPLETED`, `FAILED`, or `DISABLED`.
## Usage
### Enable `sbom_vulnerabilities`
1. Add to the `.py-secscan.conf.yml` configuration:
```yaml
...
builtins:
sbom_vulnerabilities:
enabled: true
```
### View SBOM file
1. After also enabling the built-in `sbom_vulnerabilities` and running the `py-secscan scan` command, two new files are created in the root of your project: `sbom.json` and `sbom_vulnerabilities.json`.
2. Run the command to view the SBOM files from a web page (remember, you must have py-secscan[view] installed):
```bash
py-secscan view
```
## Develop
```bash
git clone https://github.com/FabrizioCafolla/py-secscan
cd py-secscan
```
### Setup with Nix environment
**Requirements:**
| Package | Version | Install Guide |
| ------- | --------- | -------------- |
| devbox | `>=0.12.0` | [docs](https://www.jetify.com/devbox/docs/installing_devbox/#install-devbox) |
**Steps:**
```bash
devbox shell
devbox run setup
```
### Setup in Local Environment
**Requirements:**
| Package | Version | Install Guide |
| ------- | ---------- | -------------- |
| python | `>=3.12.0` | [downloads](https://www.python.org/downloads/) |
| uv | `>=0.4.3` | [docs](https://docs.astral.sh/uv/getting-started/installation/) |
**Steps:**
```bash
uv venv --python 3.12
source .activate
uv sync --all-extras
uv run pre-commit install
uv run pre-commit run --all-files
py-secscan -v scan
```
### Tests
```bash
devbox run test
uv run pre-commit run --all-files
uv run pytest tests/*
py-secscan -vv scan
```
Raw data
{
"_id": null,
"home_page": null,
"name": "py-secscan",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": null,
"keywords": "py-secscan, sast, requirements, packaging",
"author": "FabrizioCafolla",
"author_email": null,
"download_url": null,
"platform": null,
"description": "# PY SecScan\n\n\n[](https://pypi.python.org/pypi/py-secscan)\n[](https://pypi.python.org/pypi/py-secscan)\n[](https://pypi.python.org/pypi/py-secscan)\n[](https://github.com/astral-sh/uv/actions)\n[](https://github.com/astral-sh/uv)\n\nPySecScan is a lightweight and easy-to-use security scanning tool for Python projects. With a simple YAML configuration, it seamlessly integrates into any workflow, regardless of the framework or dependencies used. PySecScan automates security checks, linting, and SBOM generation, ensuring a proactive approach to code security with minimal setup.\n\n## Table of Contents \ud83d\udcda\n\n- [PY SecScan](#py-secscan)\n - [Table of Contents \ud83d\udcda](#table-of-contents-)\n - [Guide](#guide)\n - [Installation](#installation)\n - [Getting start](#getting-start)\n - [CLI](#cli)\n - [GitHub Actions](#github-actions)\n - [Pre-commit](#pre-commit)\n - [How It Works](#how-it-works)\n - [Configuration Schema](#configuration-schema)\n - [Virtual Environment](#virtual-environment)\n - [Subprocess](#subprocess)\n - [Usage](#usage)\n - [Enable `sbom_vulnerabilities`](#enable-sbom_vulnerabilities)\n - [View SBOM file](#view-sbom-file)\n - [Develop](#develop)\n - [Setup with Nix environment](#setup-with-nix-environment)\n - [Setup in Local Environment](#setup-in-local-environment)\n - [Tests](#tests)\n\n## Guide\n\n### Installation\n\n1. Ensure you have Python 3.12 or higher installed on your system. You can download it from the [official Python website](https://www.python.org/downloads/).\n\n2. Install PySecScan using pip or uv:\n\n ```bash\n pip install py-secscan\n\n # Or using uv\n uv add --dev py-secscan\n ```\n\n### Getting start\n\n1. Create a sample Python project and navigate to its root directory.\n\n2. Define the `.py-secscan.conf.yml` configuration file like this:\n\n ```yaml\n version: \"1\"\n\n packages:\n - command_name: \"echo\"\n command_args: [\"test\"]\n ```\n\n3. Run the security scan:\n\n ```bash\n py-secscan scan\n ```\n\n4. Output\n\n```plaintext\n[INFO] Subprocess command: <path>/.venv/bin/python -m ensurepip --upgrade\n\n[INFO] Subprocess command: <path>/.venv/bin/python -m pip install -r <path>/.py-secscan/requirements.txt\n\n[INFO] Execute builtins packages\n[INFO] Executing package ruff\n[INFO] Subprocess command: ruff check --fix\nAll checks passed!\n\n[INFO] Package ruff completed\n[INFO] Executing package cyclonedx-py\n[INFO] Subprocess command: cyclonedx-py environment --outfile sbom.json <path>/.venv\n\n[INFO] Package cyclonedx-py completed\n[WARNING] python package is disabled\n[INFO] {'logger_filepath': '<path>/.py-secscan/logs/py-secscan.2025-02-12.log', 'status': {'ruff': 'completed', 'cyclonedx-py': 'completed', 'python': 'disabled'}}\n[INFO] Execute packages\n[INFO] Executing package echo\n[INFO] Subprocess command: echo test\ntest\n\n[INFO] Package echo completed\n[INFO] {'logger_filepath': '<path>/.py-secscan/logs/py-secscan.2025-02-12.log', 'status': {'ruff': 'completed', 'cyclonedx-py': 'completed', 'python': 'disabled', 'echo': 'completed'}}\n```\n\n### CLI\n\nThe `py-secscan` command currently has the following options:\n\n**`scan`**: Loads the `.py-secscan.conf.yml` configuration and executes the defined commands. The security scan is, of course, proportional to what you define. By default, a linting check is performed, and the SBOM file is generated.\n\n**`view`**: Launches a web page based on Streamlit to visualize the SBOM and any detected vulnerabilities (if `builtins.sbom_vulnerabilities` is enabled). To use this command, you must install streamlit manually or via `pip install 'py-secscan[view]'` (recommended choice).\n\n> You can increase the verbosity level using the `-v` and `-vv` options.\n\n### GitHub Actions\n\n> IN PROGRESS\n\n### Pre-commit\n\n> IN PROGRESS\n\n## How It Works\n\n```mermaid\nflowchart TD\n A([\"Your Python Project\"]) -- define ---> C[\".py-secsca.conf.yml\"]\n PySecScan([\"$ py-secscan scan\"]) -- run ---> Process\n Process -. load ..-> C\n Process -- check/setup --> Env\n Process == exec ===> Subprocess[\"Subprocess\n (builtins / packages)\"]\n Subprocess == stdout/stderr ===> Output\n Subprocess -. save: FAILED or COMPLETED ..-> ExecutionStatus[\"Execution Status\"]\n Process -. save: RUNNING or DISABLED ..-> ExecutionStatus\n Subprocess -. use ..-> Env[\"Virtual Environment\"]\n Output == next: subprocess ==> Process\n```\n\nThe functionality of PySecScan is simple: using the `.py-secscan.conf.yml` configuration file, you can define the security scanning strategy for your project.\n\n**Builtins**:\n\nBy default, the `py-secscan scan` command performs a project check using `ruff` and creates the SBOM file using `cyclonedx`. Additionally, you can enable `sbom_vulnerabilities` to scan each package listed in `sbom.json` using the OSV API.\n\n**Packages**:\n\nOnce the builtins are executed, the scan retrieves the defined `packages` and runs them one by one (installing them in the virtual environment first if defined). **It is recommended to execute only Python packages related to security checks**, but any type of binary can be executed as it runs as a subprocess (be mindful of `FORBIDDEN_OPERATORS`, which prevent the execution of certain commands).\n\n\\* Package installation is limited to Python packages available on PyPI.\n\n### Configuration Schema\n\nThe `.py-secscan.conf.yml` configuration file must contain at least the `version` key and is structured into several optional sections to customize `py-secscan`'s behavior. For more details view [jsonschema version 1](py_secscan/scan/parser/v1/pysecscan.schema.json)\n\n**1. Version**:\n\n- `version` (*required*): A string that defines the parser version to use. Currently supported versions: `1`.\n\n**2. Options**:\n\n- `debug` (*default: false | optional*): Enables debug mode.\n- `env` (*default: {} | optional*): Dictionary of environment variables.\n- `pysecscan_dirpath` (*default: \".py-secscan\" | optional*): Path to the PySecScan directory.\n- `venv_dirpath` (*default: \".venv\" | optional*): Path to the virtual environment directory.\n- `enabled` (*default: true | optional*): Enables/disables security checks.\n- `disable_builtins` (*default: false | optional*): Disables all built-in commands.\n- `disable_venv_check` (*default: false | optional*): Disables the virtual environment check, allowing execution in a non-virtual environment.\n- `disable_venv_creation` (*default: false | optional*): Disables automatic virtual environment creation.\n- `disable_venv_install` (*default: false | optional*): Disables the installation of packages defined in the `packages` directive in the virtual environment.\n- `additional_forbidden_commands` (*default: [] | optional*): Additional list of forbidden commands that will be blocked.\n\n**3. Packages**:\n\nList of commands to execute.\n\n- `command_name` (*required*): Name of the command to execute.\n- `command_args` (*default: [] | optional*): List of string arguments to pass to the command.\n- `install` (*default: {} | optional*):\n - `enabled` (*default: false | optional*): If true, the package will be installed automatically.\n - `package_name` (*default: \"\" | optional*): Used to define the package name for installation via `pip install <package_name>==<version>`. If not defined, it defaults to `command_name`.\n - `version` (*default: \"latest\" | optional*): Package version.\n - `extras` (*default: [] | optional*): Extra installation options.\n- `enabled`: If false, the package will not be executed and will be marked as `DISABLED`.\n- `on_error_continue`: If true, errors will not stop the execution of subsequent packages.\n\n**4. Builtins**:\n\nBuiltins are predefined packages that can be enabled/disabled or configured differently at any time.\n\nThe `ruff` builtin automatically performs an initial linting check on the entire project.\n\n- `ruff`:\n - `command_name`: \"ruff\"\n - `command_args`: [\"check --fix\"]\n - `enabled`: True\n - `on_error_continue`: False\n\nThe `cyclonedx` builtin automatically scans the virtual environment and generates an SBOM file containing all dependencies.\n\n- `cyclonedx`:\n - `command_name`: \"cyclonedx-py\"\n - `command_args`: [\n \"environment --outfile sbom.json <venv_path>\"\n ]\n - `enabled`: True\n - `on_error_continue`: False\n\nThe `sbom_vulnerabilities` builtin, when enabled, scans for vulnerabilities in each dependency listed in the SBOM file using the [OSV](https://osv.dev/) API.\n\n- `sbom_vulnerabilities`:\n - `command_name`: \"python -m py_secscan.modules.builtins.sbom_vulnerabilities\"\n - `command_args`: [\"sbom.json sbom_vulnerabilities.json\"]\n - `enabled`: False\n - `on_error_continue`: True\n\n### Virtual Environment\n\nA virtual environment (venv) must be present at the specified path and activated before executing the `py-secscan scan` command. Before execution, a check ensures that the correct venv is being used (default: `<project-path>/.venv`).\n\nOnce verified, all defined packages with `install.enabled: true` are installed. A `.py-secscan/requirements.txt` file is created, containing the list of packages installed at runtime by PySecScan.\n\nThis allows you to destroy the venv without worrying about losing installed packages since they will always be reinstalled based on the configuration.\n\n> \u26a0\ufe0f WARNING: Disabling the virtual environment check is possible but not recommended, as it could lead to installing packages globally. This should be used only in CI/CD contexts by setting `options.disable_venv_check` to `true`.\n\n### Subprocess\n\nAs shown in the diagram, every execution of a `builtin` or `package` is a Python subprocess. The executed command is sanitized and checked to prevent harmful commands. Each execution status is recorded as `RUNNING`, `COMPLETED`, `FAILED`, or `DISABLED`.\n\n## Usage\n\n### Enable `sbom_vulnerabilities`\n\n1. Add to the `.py-secscan.conf.yml` configuration:\n\n ```yaml\n ...\n\n builtins:\n sbom_vulnerabilities:\n enabled: true\n ```\n\n### View SBOM file\n\n1. After also enabling the built-in `sbom_vulnerabilities` and running the `py-secscan scan` command, two new files are created in the root of your project: `sbom.json` and `sbom_vulnerabilities.json`.\n2. Run the command to view the SBOM files from a web page (remember, you must have py-secscan[view] installed):\n\n ```bash\n py-secscan view\n ```\n\n## Develop\n\n```bash\ngit clone https://github.com/FabrizioCafolla/py-secscan\n\ncd py-secscan\n```\n\n### Setup with Nix environment\n\n**Requirements:**\n\n| Package | Version | Install Guide |\n| ------- | --------- | -------------- |\n| devbox | `>=0.12.0` | [docs](https://www.jetify.com/devbox/docs/installing_devbox/#install-devbox) |\n\n**Steps:**\n\n```bash\ndevbox shell\ndevbox run setup\n```\n\n### Setup in Local Environment\n\n**Requirements:**\n\n| Package | Version | Install Guide |\n| ------- | ---------- | -------------- |\n| python | `>=3.12.0` | [downloads](https://www.python.org/downloads/) |\n| uv | `>=0.4.3` | [docs](https://docs.astral.sh/uv/getting-started/installation/) |\n\n**Steps:**\n\n```bash\nuv venv --python 3.12\nsource .activate\n\nuv sync --all-extras\nuv run pre-commit install\nuv run pre-commit run --all-files\n\npy-secscan -v scan\n```\n\n### Tests\n\n```bash\ndevbox run test\n\nuv run pre-commit run --all-files\nuv run pytest tests/*\npy-secscan -vv scan\n```\n",
"bugtrack_url": null,
"license": null,
"summary": "PySecScan is the tool that allows you to perform security scans in your Python project through a simple YAML configuration.",
"version": "0.1.1",
"project_urls": null,
"split_keywords": [
"py-secscan",
" sast",
" requirements",
" packaging"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "d9592bc8b5ff6d7ec464054c1f1f7981f21567bf35664d36c40007932ad2ef4e",
"md5": "7eda02c2cf9b43c515dc76daddb641f2",
"sha256": "4b01c6f1f9054b710b5cc85cd2814de920af0d161bad96a0e62faa3e6180aff1"
},
"downloads": -1,
"filename": "py_secscan-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7eda02c2cf9b43c515dc76daddb641f2",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 21043,
"upload_time": "2025-02-16T17:58:20",
"upload_time_iso_8601": "2025-02-16T17:58:20.105502Z",
"url": "https://files.pythonhosted.org/packages/d9/59/2bc8b5ff6d7ec464054c1f1f7981f21567bf35664d36c40007932ad2ef4e/py_secscan-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-16 17:58:20",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "py-secscan"
}
