Metadata-Version: 2.1
Name: damv1paramikossh-forscriptspipeline
Version: 0.1.0
Summary: A Python package for executing SSH commands via Paramiko in CI/CD pipeline scripts.
Home-page: UNKNOWN
Author: dhonyabumuhammad (Djogja)
Author-email: baba-rtw24150@tutamail.com
License: UNKNOWN
Keywords: paramiko,ssh,rsakey,openssh,djogja,pipeline-scripts
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: License :: OSI Approved :: MIT License
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: paramiko>=3.0.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

| Operating System | Architecture | Status |
|------------------|--------------|--------|
| Linux            | x86_64       | Supported |
| macOS            | ARM64 (Apple Silicon) | Supported |
| macOS            | x86_64 (Intel) | Supported |

### Installation

Install the package directly from PyPI using pip:

```bash
pip install damv1paramikossh_forscriptspipeline
```

### CLI Syntax

The package registers a global executable named `damv1paramikossh_forscriptspipeline`.

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

#### Parameters

| Position | Parameter | Description |
|----------|-----------|-------------|
| 1 | `SERVER` | The IP address or hostname of the target server. |
| 2 | `SSH_USERNAME` | The SSH user account on the remote server. |
| 3 | `SSH_PORT` | The SSH port number (typically `22`). |
| 4 | `PASSWORD_OR_KEY` | Either a plain-text password or the raw string content of an OpenSSH private key. Auto-detected by the tool. |
| 5 | `COMMAND` | The shell command to execute on the remote server. **Must be enclosed in quotes.** |

#### 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)

```bash
# 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

```bash
# 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**.

```yaml
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`.

```yaml
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
```text
[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
```text
[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

| Issue | Cause | Solution |
|-------|-------|----------|
| `ModuleNotFoundError` | Package not installed or directory name contains hyphens | Run `pip install -e .` and ensure the module directory uses underscores (`_`), not hyphens (`-`). |
| `dquote>` prompt in terminal | Unescaped special characters (`$`, `!`) inside double quotes | Wrap the credential and command arguments in **single quotes** (`'`). |
| `SSHException: not a valid private key` | Password provided but interpreted as key, or corrupted key content | Verify the key content includes proper headers, or ensure the password does not accidentally contain key-like strings. |
| Pipeline fails silently | Exit code not propagated | The tool automatically propagates the remote command's exit code. Verify the remote command itself returns a non-zero status on failure. |

### 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.

