{"id":34031232,"url":"https://github.com/pfrest/pfsense-vshell","last_synced_at":"2026-05-15T07:13:41.235Z","repository":{"id":43532777,"uuid":"252294593","full_name":"pfrest/pfsense-vshell","owner":"pfrest","description":"A command line tool and Python3 module to run remote shell commands on pfSense without SSH","archived":false,"fork":false,"pushed_at":"2026-02-01T18:55:25.000Z","size":2281,"stargazers_count":19,"open_issues_count":1,"forks_count":7,"subscribers_count":3,"default_branch":"master","last_synced_at":"2026-02-02T00:52:51.846Z","etag":null,"topics":["automation","command-line","command-line-tool","firewall","network","pfsense","pip","python3","shell"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/pfsense-vshell/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pfrest.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"jaredhendrickson13"}},"created_at":"2020-04-01T21:51:34.000Z","updated_at":"2026-02-01T18:55:21.000Z","dependencies_parsed_at":"2025-06-01T16:21:33.147Z","dependency_job_id":"73ad6795-6f1e-47af-8f53-4d89368dba14","html_url":"https://github.com/pfrest/pfsense-vshell","commit_stats":null,"previous_names":["pfrest/pfsense-vshell"],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/pfrest/pfsense-vshell","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pfrest%2Fpfsense-vshell","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pfrest%2Fpfsense-vshell/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pfrest%2Fpfsense-vshell/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pfrest%2Fpfsense-vshell/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pfrest","download_url":"https://codeload.github.com/pfrest/pfsense-vshell/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pfrest%2Fpfsense-vshell/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30395669,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-11T18:46:22.935Z","status":"ssl_error","status_checked_at":"2026-03-11T18:46:17.045Z","response_time":84,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["automation","command-line","command-line-tool","firewall","network","pfsense","pip","python3","shell"],"created_at":"2025-12-13T18:09:05.562Z","updated_at":"2026-05-15T07:13:41.211Z","avatar_url":"https://github.com/pfrest.png","language":"Python","funding_links":["https://github.com/sponsors/jaredhendrickson13"],"categories":[],"sub_categories":[],"readme":"# pfSense vShell\n\n[![Quality](https://github.com/jaredhendrickson13/pfsense-vshell/actions/workflows/quality.yml/badge.svg)](https://github.com/jaredhendrickson13/pfsense-vshell/actions/workflows/quality.yml)\n[![Release](https://github.com/jaredhendrickson13/pfsense-vshell/actions/workflows/release.yml/badge.svg)](https://github.com/jaredhendrickson13/pfsense-vshell/actions/workflows/release.yml)\n[![CodeQL](https://github.com/jaredhendrickson13/pfsense-vshell/actions/workflows/codeql.yml/badge.svg)](https://github.com/jaredhendrickson13/pfsense-vshell/actions/workflows/codeql.yml)\n\npfSense vShell is a command line tool and Python module that enables users to remotely enter shell commands on a pfSense\nhost without enabling `sshd`. This allows administrators to automate installation of packages, enable `sshd`, and make other backend\nchanges out of the box.\n\n## Installation\npfSense vShell requires Python3/Pip3 for installation\u003cbr\u003e\n\nTo install:\u003cbr\u003e\n`pip install pfsense-vshell` \n\nTo uninstall:\u003cbr\u003e\n`pip uninstall pfsense-vshell`\n\n## Command Line\n\n### Usage \u0026 Syntax\n```\nusage: pfsense-vshell [-h] --host HOST [--virtual_shell] [--command COMMAND] --username USERNAME [--password PASSWORD] [--scheme {http,https}] [--port PORT] [--timeout TIMEOUT] [--shell_timeout SHELL_TIMEOUT] [--no_verify] [--version] [--verbose]\n```\n\n| Command         | Shorthand | Required                              | Description                                                                                    | Example Usage           |\n|-----------------|-----------|---------------------------------------|------------------------------------------------------------------------------------------------|-------------------------|\n| --host          | -i        | Yes (except with --help or --version) | Set the IP or hostname of the remote pfSense host                                              | --host HOST             |\n| --command       | -c        | No                                    | Run a single shell command                                                                     | --command COMMAND       |\n| --virtual_shell | -s        | No                                    | Start a interactive virtual shell                                                              | --virtual_shell         |\n| --help          | -h        | No                                    | Display the help page                                                                          | --help                  |\n| --version       | -V        | No                                    | Display the current version                                                                    | --version               |\n| --username      | -u        | Yes (except with --help or --version) | Set the username to login with                                                                 | --username USERNAME     |\n| --password      | -p        | No                                    | Set the password to login with. User will be prompted for a password if unspecified.           | --password PASSWORD     |\n| --port          | -P        | No                                    | Set the TCP port of pfSense's webConfigurator                                                  | --port PORT             |\n| --scheme        | -w        | No                                    | Set the HTTP protocol scheme. `http` or `https`                                                | --scheme SCHEME         |\n| --no_verify     | -k        | No                                    | Disable SSL certificate verification                                                           | --no_verify             |\n| --timeout       | -t        | No                                    | Set the connection timeout value (in seconds)                                                  | --timeout TIMEOUT       |\n| --shell_timeout | -z        | No                                    | Set the virtual shell session timeout value (in seconds). Only available with --virtual_shell. | --shell_timeout TIMEOUT |\n| --verbose       | -v        | No                                    | Enable verbose logging                                                                         | --verbose               |\n\n### Examples\nBelow are some examples of common use cases for pfsense-vshell:\u003cbr\u003e\n\n1: Run a single shell command (with inline authentication)\n```shell script\n$ pfsense-vshell --host 127.0.0.1 --command \"cat /etc/version\" --username admin --password pfsense\n2.4.5-RELEASE\n```\n2: Start an interactive virtual shell session to run multiple commands\n```shell script\n$ pfsense-vshell --host 127.0.0.1 --virtual_shell --username admin --password pfsense\n---Virtual shell established---\nadmin@127.0.0.1:/usr/local/www $ uname -a\nFreeBSD pfSense.localdomain 11.3-STABLE FreeBSD 11.3-STABLE #236 21cbb70bbd1(RELENG_2_4_5): Tue Mar 24 15:26:53 EDT 2020#     root@buildbot1-nyi.netgate.com:/build/ce-crossbuild-245/obj/amd64/YNx4Qq3j/build/ce-crossbuild-245/sources/FreeBSD-src/sys/pfSense  amd64\nadmin@127.0.0.1:/usr/local/www $ exit\n---Virtual shell terminated---\n```\n3: Run a single command to enable `sshd` on pfSense\n```shell script\n$ pfsense-vshell --host 127.0.0.1 --command \"pfSsh.php playback enablesshd\" --username admin --password pfsense\n```\n\n4: Run a single command to install a package on pfSense\n```shell script\n$ pfsense-vshell --host 127.0.0.1 --command \"pkg install -y pfSense-pkg-nmap\" --username admin --password pfsense\n```\n\n5: Display pfSense vShell version\n```shell script\n$ pfsense-vshell --version\npfsense-vshell v2.0.3\n```\n\n### Notes\n- When using `--virtual_shell`, you may enter the command `history` to display commands executed since the virtual shell\nsession started.\n- Interactive commands cannot be run within pfSense vShell, there is no way to add additional input after you have run \nyour command. \n- Some older versions (pre-2.3) may not work properly. Always test functionality for running against production systems.\n- By default, you are placed in the webConfigurator's web-root directory (/usr/local/www/). You cannot change directories.\nAny file interaction will be relative to this directory if not absolute.\n- By default, any command run within pfSense vShell has root access. There is no way to change this so be careful.\n- Your pfSense user must have access to the Diagnostics \u003e Command Prompt page within the webConfigurator.\n\n## Python3 Module\nAfter installing the package, the `pfsense_vshell` module will also be made available to your Python3 scripts.\n\n### Classes\n```\nPFClient(host, username, password, port=443, scheme='https', timeout=30, verify=True)\n:   Initializes the object at creation\n    :param host: (string) the IP or hostname of the remote pfSense host\n    :param username: (string) the pfSense username to authenticate as.\n    :param password: (string) the password for the pfSense username.\n    :param port: (int) the remote TCP port of pfSense's webConfigurator. Defaults to 443.\n    :param scheme: (string) the HTTP scheme to use. http or https. Defaults to https.\n    :param timeout: (int) the timeout value in seconds for HTTP requests. Defaults to 30.\n    :param verify: (bool) true to enable certificate verification, false to disable. Defaults to true.\n\n    ### Properties\n    obj.host\n    :   (string) the IP or hostname of the remote pfSense host\n    \n    obj.username\n    :   (string) the pfSense username to authenticate as\n    \n    obj.password\n    :   (string) the password for the pfSense username\n    \n    obj.port\n    :   (int) the remote TCP port of pfSense's webConfigurator\n    \n    obj.scheme\n    :   (string) the HTTP scheme to use\n    \n    obj.timeout\n    :   (int) the timeout value in seconds for HTTP requests\n    \n    obj.verify\n    :   (bool) certificate verification toggle\n    \n    obj.history\n    :   (array) previous commands executed\n    \n    obj.log\n    :   (array) logged events\n    \n    obj.last_request\n    :   (object) the last request object used\n    \n\n    ### Static methods\n\n    version()\n    :   Provides the current version of pfsense vShell\n        :return: (string) the current pfSense vShell version\n\n    ### Methods\n\n    authenticate(self)\n    :   Attempts to authenticate using the objects current properties\n        :return: (bool) true if authentication was successful, false if it wasn't\n\n    get_csrf_token(self, uri)\n    :   Retrieves the current CSRF token for a page\n        :param uri: (string) the URI (e.g. index.php) to retrieve the CSRF token from\n        :return: (string) the CSRF token\n\n    has_dns_rebind_error(self, req=None)\n    :   Checks if the objects host encounters a DNS rebind error when connecting\n        :param req: (object) optionally provide an existing Response object created by the requests module\n        :return: (bool) true if a DNS rebind error was found, false if it wasn't\n\n    is_host_pfsense(self, req=None)\n    :   Checks if the remote host is running pfSense. This is intended to protect clients from accidentally sending\n        their login credentials to the wrong host as well as prevent hosts from spamming non-pfSense hosts.\n        :param req: (object) optionally provide an existing Response object created by the requests module\n        :return: (bool) true if the host is running pfSense, false if it is not\n\n    request(self, uri, method='GET', data=None)\n    :   Makes HTTP requests on behalf of our object\n        :param uri: (string) the URI (e.g. /index.php) to request on the remote host\n        :param method: (string) the HTTP method to use in the request (e.g. POST, GET)\n        :param data: (dict) the request body data to send in the request\n        :return: (object) the Response object created by the requests module\n\n    run_command(self, cmd)\n    :   Executes a shell command on the remote host using pfSense's diag_command.php page\n        :param cmd: (string) a shell command to execute\n        :return: (string) output of the shell command\n\n    url(self)\n    :   Formats a full URL with the objects current property values\n        :return: (string) full URL of our object\n\nPFError(code, message)\n:   Error object used by the PFVShell class\n\n    ### Ancestors (in MRO)\n\n    * builtins.Exception\n    * builtins.BaseException\n```\n\n### Examples\n```python\nimport pfsense_vshell\n\n# Create our PFClient object\nvshell = pfsense_vshell.PFClient(\"127.0.0.1\", username=\"admin\", password=\"password\")\n\n# Run command to install package on pfSense\nvshell.run_command(\"pkg install -y pfSense-pkg-sudo\")\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpfrest%2Fpfsense-vshell","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpfrest%2Fpfsense-vshell","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpfrest%2Fpfsense-vshell/lists"}