damv1paramikossh-forscriptspipeline 0.1.0

damv1paramikossh_forscriptspipeline

A specialized Python package designed to execute remote SSH commands via Paramiko, specifically engineered for CI/CD pipeline scripts (e.g., Bitbucket Pipelines, GitHub Actions, GitLab CI).

Overview

This package provides a robust command-line interface to authenticate with remote servers and execute shell commands. It features automatic credential detection, seamlessly handling both password-based and private key-based authentication without requiring explicit configuration flags.

The tool systematically captures standard output, standard error, and exit codes to ensure reliable integration with pipeline failure/success detection mechanisms.

Key Features

• Automatic Credential Detection: Intelligently distinguishes between OpenSSH private keys (RSA, Ed25519, ECDSA, DSA) and plain-text passwords based on content signature.
• Multi-Key Format Support: Natively handles BEGIN OPENSSH PRIVATE KEY, BEGIN RSA PRIVATE KEY, BEGIN EC PRIVATE KEY, and BEGIN DSA PRIVATE KEY formats.
• Pipeline-Ready Exit Codes: Propagates the remote command's exit status directly to the shell, enabling accurate CI/CD failure detection.
• Cross-Platform Compatibility: Tested and supported on Linux (x86_64) and macOS (ARM64 / x86_64).
• Clean Log Output: Structured output formatting optimized for CI/CD log readability.

Supported Environments

Installation

Install the package directly from PyPI using pip:

pip install damv1paramikossh_forscriptspipeline

CLI Syntax

The package registers a global executable named damv1paramikossh_forscriptspipeline.

damv1paramikossh_forscriptspipeline <SERVER> <SSH_USERNAME> <SSH_PORT> <PASSWORD_OR_KEY> "<COMMAND>"

Parameters

Credential Detection Logic

The tool inspects the 4th argument for the presence of any of the following headers:

• BEGIN OPENSSH PRIVATE KEY
• BEGIN RSA PRIVATE KEY
• BEGIN EC PRIVATE KEY
• BEGIN DSA PRIVATE KEY

If any header is detected, the credential is treated as a private key. Otherwise, it is treated as a password.

Usage Examples

Example 1: Local Testing on MacBook Pro M1 (Password Authentication)

# 1. Create and activate virtual environment
python3 -m venv venv
source venv/bin/activate

# 2. Install dependencies and the package in editable mode
pip3 install -r ./requirements.txt
pip install -e .

# 3. Execute the command (use single quotes to preserve special characters)
damv1paramikossh_forscriptspipeline '103.186.30.214' 'ubuntu' '22' 'p4$$W0Rd2025!' 'uname -a'

Example 2: Local Testing with Private Key

# Read the private key into a shell variable (stripping header/footer is optional)
MY_SSH_KEY=$(cat ~/.ssh/id_ed25519 | grep -v "BEGIN" | grep -v "END" | tr -d '\n')

# Execute the command
damv1paramikossh_forscriptspipeline '103.186.30.214' 'ubuntu' '22' "$MY_SSH_KEY" 'kubectl get pods -n sit'

Example 3: Bitbucket Pipeline (Password Authentication)

Store SERVER, SSH_USERNAME, SSH_PORT, and SSH_KEY (containing the password) in Repository Variables.

pipelines:
  default:
    - step:
        name: Execute Remote Command via Password
        image: python:3.10-slim
        script:
          - pip install damv1paramikossh_forscriptspipeline
          - damv1paramikossh_forscriptspipeline ${SERVER} ${SSH_USERNAME} ${SSH_PORT} "${SSH_KEY}" "kubectl rollout restart deployment/inbound-wms -n sit"

Example 4: Bitbucket Pipeline (Private Key Authentication - Recommended)

Store the full private key content (including -----BEGIN OPENSSH PRIVATE KEY----- header and -----END OPENSSH PRIVATE KEY----- footer) in a Repository Variable named SSH_PRIVATE_KEY.

pipelines:
  default:
    - step:
        name: Execute Remote Command via SSH Key
        image: python:3.10-slim
        script:
          - pip install damv1paramikossh_forscriptspipeline
          - damv1paramikossh_forscriptspipeline ${SERVER} ${SSH_USERNAME} ${SSH_PORT} "${SSH_PRIVATE_KEY}" "kubectl rollout restart deployment/inbound-wms -n sit"

Expected Output

Successful Execution

[INFO] Initializing SSH execution via Paramiko.
[INFO] Connecting to ubuntu@103.186.30.214:22...
[INFO] Detected Password format. Authenticating with password...
[INFO] Connection established. Executing command...
[OUTPUT]
Linux prod-server-01 5.15.0-91-generic #101-Ubuntu SMP x86_64 GNU/Linux
[INFO] Command executed successfully.

Authentication Failure

[INFO] Initializing SSH execution via Paramiko.
[INFO] Connecting to ubuntu@103.186.30.214:22...
[INFO] Detected Password format. Authenticating with password...
[ERROR] Authentication failed. Please verify your credentials (password or private key).

Troubleshooting

Security Recommendations

For CI/CD pipeline environments, SSH Private Key authentication is strongly recommended over password authentication for the following reasons:

• Passwords are susceptible to logging exposure if pipeline masking is misconfigured.
• Private keys can be rotated centrally without modifying multiple pipeline variables.
• Key-based authentication eliminates brute-force attack vectors on exposed servers.
• Industry-standard DevSecOps practice mandates key-based automation credentials.

Maintainer

• Author: dhonyabumuhammad (Djogja)
• Contact: baba-rtw24150@tutamail.com
• Keywords: paramiko, ssh, rsakey, openssh, djogja, pipeline-scripts

License

This project is licensed under the MIT License. See the LICENSE file for details.