lukcz/rpc-shutdown repository overview

⁠Description

Rpc-shutdown is a Dockerized Flask-based service that provides a secure REST API for remotely shutting down Windows machines using the net rpc shutdown command. Designed for streamlined deployment and easy integration, this service ensures that only authorized users can execute shutdown commands, enhancing the security and manageability of your networked systems.

⁠Features

• Secure API Key Authentication: Protects API endpoints with a robust API key mechanism to ensure that only authorized requests are processed.
• Rate Limiting: Implements request rate limiting to prevent abuse and ensure fair usage of the API.
• Optional Shutdown Delay: Allows scheduling the shutdown by specifying a delay in seconds, providing flexibility in managing shutdown operations.
• Custom Shutdown Messages: Send a custom message to users on the target Windows machine before it shuts down.
• Comprehensive Logging: Logs all activities, including successful commands and unauthorized access attempts, aiding in monitoring and troubleshooting.
• Non-Root Execution: Runs the application as a non-root user within the Docker container, adhering to best security practices.
• Docker Compose Support: Simplifies deployment and management of the service using Docker Compose.

⁠Usage

⁠1. Prerequisites

• Docker Installed: Ensure Docker is installed on your system. Verify by running:

  docker --version
  

  Copy

• Docker Compose Installed: Ensure Docker Compose is installed. Verify with:

  docker compose version
  

  Copy

⁠2. Pulling the Image from Docker Hub

First, log in to Docker Hub:

docker login

Then, pull the rpc-shutdown image:

docker pull lukcz/rpc-shutdown:latest

⁠3. Running the Container

You can run the container using Docker Compose or directly with Docker.

Using Docker Compose:

Create a docker-compose.yml file:

version: '3.8'

services:
  rpc-shutdown:
    image: lukcz/rpc-shutdown:latest
    container_name: rpc-shutdown
    environment:
      - API_KEY=your_actual_api_key  # Replace with your actual API key
    ports:
      - "5000:5000"
    restart: unless-stopped

Then, start the service:

docker compose up -d

Using Docker Run:

docker run -d \
  --name rpc-shutdown \
  -p 5000:5000 \
  -e API_KEY=your_actual_api_key \  # Replace with your actual API key
  lukcz/rpc-shutdown:latest

⁠4. Interacting with the API

curl -H "x-api-key: your_actual_api_key" http://localhost:5000/status

Expected Response:

{
  "status": "API is running"
}

Execute Shutdown Command without Delay:

curl -X POST http://localhost:5000/shutdown \
    -H "Content-Type: application/json" \
    -H "x-api-key: your_actual_api_key" \
    -d '{
          "target_ip": "192.168.1.100",
          "username": "admin",
          "password": "password123"
        }'

Expected Response on Success:

{
  "output": "Shutdown command executed successfully."
}

Execute Shutdown Command with Delay and Message:

curl -X POST http://localhost:5000/shutdown \
     -H "Content-Type: application/json" \
     -H "x-api-key: your_actual_api_key" \
     -d '{
           "target_ip": "192.168.1.100",
           "username": "admin",
           "password": "password123",
           "delay": 300,
           "message": "System maintenance in 5 minutes. Please save your work."
         }'

Expected Response on Success:

{
  "output": "Shutdown command executed successfully."
}

⁠5. Configuration

• Environment Variables:
  • API_KEY: A strong, unique API key used to authenticate requests to the API. Ensure this key is kept secret and is not exposed publicly.

⁠6. Security Considerations

• API Exposure: Since the API is exposed over HTTP on port 5000, ensure that access to this port is restricted to trusted networks or secured using additional network-level protections such as firewalls or VPNs.

• API Key Management: Use a strong, unique API key and rotate it regularly to enhance security. Avoid hardcoding sensitive information; consider using Docker Secrets or environment variable files (.env) with proper access controls.

• Least Privilege Principle: The Docker container runs the application as a non-root user to minimize potential security risks.

• Logging and Monitoring: Regularly monitor the container logs to detect any unauthorized access attempts or anomalies.

  docker logs rpc-shutdown
  

  Copy

⁠7. Best Practices

• Use Docker Compose for Management: Utilize Docker Compose to manage and orchestrate the container, making it easier to scale and maintain.
• Keep Dependencies Updated: Regularly update the Docker image and its dependencies to incorporate the latest security patches and features.
• Backup Configurations: Maintain backups of your docker-compose.yml and any configuration files to prevent data loss.

⁠8. Troubleshooting

⁠Issues with Remote Shutdown Not Working

If the remote shutdown is not working, and you receive errors such as:

• Could not initialise pipe winreg. Error was NT_STATUS_OBJECT_NAME_NOT_FOUND
• Shutdown of remote machine failed result was: WERR_CALL_NOT_IMPLEMENTED

You may need to adjust settings on the Windows machine you're attempting to shut down.

⁠1. Start Remote Registry Service

The Remote Registry service must be running:

1. Press Win + R, type services.msc, and press Enter.
2. Scroll down and find Remote Registry.
3. Double-click it and set Startup type to Automatic.
4. Click Apply, then Start, and then OK.

⁠2. Allow Windows Management Instrumentation (WMI) in Windows Firewall

Allow WMI through the firewall:

1. Click on the Start button and type Allow an app through Windows Firewall.
2. Click on the result to open the settings.
3. Scroll down to Windows Management Instrumentation (WMI).
4. Click on Change settings.
5. Check the box under the Private column.
6. Click OK.

⁠3. Modify Local Policy in Windows Registry

Add a specific registry key to allow remote shutdown:

1. Press Win + R, type regedit, and press Enter to open the Registry Editor.

2. Navigate to:

   HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Policies\System
   

   Copy

3. Right-click on the System folder, select New > DWORD (32-bit) Value.

4. Name it LocalAccountTokenFilterPolicy.

5. Double-click the new entry and set the Value data to 1.

6. Click OK and close the Registry Editor.

7. Restart the Windows Machine

After making the above changes, restart the Windows machine to ensure all settings take effect.

⁠General Troubleshooting Tips

• Permission Denied Errors:

  • Ensure your user is added to the docker group to run Docker commands without sudo.
  • Verify that the Docker daemon is running.

• Container Name Conflicts:

  • If you encounter conflicts with container names, stop and remove existing containers or use unique names.

• smbd Command Not Found:

  • Ensure that the samba package is correctly installed in the Docker image. Rebuild the image if necessary.

• Rate Limiting Issues:

  • Adjust rate limiting settings in api_server.py if legitimate traffic is being restricted.

⁠9. License

MIT License	

⁠10. Contact

For any questions or support, please contact [email protected]⁠.