PyNinja

Lightweight OS-agnostic service monitoring API

Platform Supported

Deployments

Kick off

Recommendations

• Install python 3.11 or above
• Use a dedicated virtual environment

Install PyNinja

python -m pip install pyninja

Initiate - IDE

import pyninja


if __name__ == '__main__':
    pyninja.start()

Initiate - CLI

pyninja start

Use pyninja --help for usage instructions.

Environment Variables

Basic API

• APIKEY - API Key for authentication.
• SWAGGER_UI_PARAMETERS - Dictionary of parameters to be included in the Swagger UI.
• NINJA_HOST - Hostname for the API server.
• NINJA_PORT - Port number for the API server.
• HOST_PASSWORD - Password to authenticate sudo commands on the server. Applies only for POSIX systems.
• OBSERVABILITY_SESSION - Session timeout for observability metrics.

Functional improvements

• RATE_LIMIT - List of dictionaries with max_requests and seconds to apply as rate limit.
• LOG_CONFIG - Logging configuration file path.

Remote execution and FileIO

• REMOTE_EXECUTION - Boolean flag to enable remote execution.
• API_SECRET - Secret access key for running commands on server remotely.
• DATABASE - FilePath to store the auth database that handles the authentication errors.

⚠️ Warning: Enabling remote execution carries significant security risks.
To enhance security, it is mandatory to use multifactor authentication (MFA) token.

Multifactor Authentication (MFA)

• MFA_TIMEOUT - Timeout duration for MFA in seconds.

• MFA_RESEND_DELAY - Resend duration for MFA in seconds. Cool off period before a new MFA can be requested.

• Email

  • GMAIL_USER - Gmail username for MFA.
  • GMAIL_PASS - Gmail password for MFA.
  • RECIPIENT - Recipient email address for MFA. Defaults to GMAIL_USER

• Ntfy

  • NTFY_URL - Ntfy server URL.
  • NTFY_TOPIC - Subscribed ntfy topic.

  Include NTFY_USERNAME and NTFY_PASSWORD if the topic is protected.

• Telegram

  • TELEGRAM_TOKEN - Telegram bot token.
  • TELEGRAM_CHAT_ID - Telegram chat ID to send MFA.

• Authenticator

  • AUTHENTICATOR_APP - Authenticator app name. Defaults to PyNinja.
  • AUTHENTICATOR_USER - Authenticator username. Defaults to thevickypedia.
  • AUTHENTICATOR_TOKEN - MFA Authenticator token.

  To generate a QR code for any authenticator application:

  Code

  import pyninja
  pyninja.otp.generate_qr(show_qr=True)

  CLI

  pyninja --mfa

  📓 Generating an authenticator token using PyNinja is the simplest ways to set up MFA authentication. However, the trade-off is that the token is short-lived. Each MFA passcode is only valid for 30 seconds.

Monitoring UI

• MONITOR_USERNAME - Username to authenticate the monitoring page.
• MONITOR_PASSWORD - Password to authenticate the monitoring page.
• MONITOR_SESSION - Session timeout for the monitoring page.
• DISK_REPORT - Boolean flag to enable disk report feature using PyUdisk.
• MAX_CONNECTIONS - Maximum number of monitoring sessions allowed in parallel.
• PROCESSES - List of process names to include in the monitor page.
• SERVICES - List of service names to include in the monitor page.
• SERVICE_LIB - Library path to retrieve service info.
• SMART_LIB - Library path for S.M.A.R.T metrics using PyUdisk.
• GPU_LIB - Library path to retrieve GPU names using PyArchitecture.
• DISK_LIB - Library path to retrieve disk info using PyArchitecture.
• PROCESSOR_LIB - Library path to retrieve processor name using PyArchitecture.

Certificates

• CERTBOT_PATH - Path to the certbot binary for certificate management.
• CERT_SCAN - Dictionary of key-value pairs threshold and schedule to set up certificate expiry monitoring.
  • threshold - Expiry threshold in days to trigger alerts.
  • schedule - Time in %H:%M format to run the certificate monitoring job daily.

macOS Specific Binaries

• OSASCRIPT - Path to the osascript binary for macOS. Defaults to /usr/bin/osascript
• MDLS - Path to the mdls binary for macOS. Defaults to /usr/bin/mdls
• OPEN - Path to the open binary for macOS. Defaults to /usr/bin/open

Windows Specific Binaries

• pwsh - Path to the pwsh binary for Windows. Defaults to C:\Program Files\PowerShell\7\pwsh.exe

📓 Certain environment variables like SERVICES and PROCESSS are case-sensitive

Refer samples directory for examples.

Coding Standards

Docstring format: Google

Styling conventions: PEP 8 and isort

Release Notes

Requirement

python -m pip install gitverse

Usage

gitverse-release reverse -f release_notes.rst -t 'Release Notes'

Linting

pre-commit will ensure linting, run pytest, generate runbook & release notes, and validate hyperlinks in ALL
markdown files (including Wiki pages)

Requirement

python -m pip install sphinx pre-commit recommonmark

Usage

pre-commit run --all-files

Pypi Package

https://pypi.org/project/PyNinja/

Runbook

https://thevickypedia.github.io/PyNinja/

License & copyright

© Vignesh Rao

Licensed under the MIT License