{"id":15779788,"url":"https://github.com/rgl/winps","last_synced_at":"2026-01-23T12:54:12.496Z","repository":{"id":139753736,"uuid":"539926669","full_name":"rgl/winps","owner":"rgl","description":"Remote execute a command in a Windows machine using WinRM/WinRS/RDP","archived":false,"fork":false,"pushed_at":"2025-05-13T19:10:32.000Z","size":12,"stargazers_count":1,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-05-13T20:38:34.663Z","etag":null,"topics":["psrp","rdp","winrm","winrs"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rgl.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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}},"created_at":"2022-09-22T10:34:38.000Z","updated_at":"2025-05-13T19:10:35.000Z","dependencies_parsed_at":"2023-12-13T07:23:24.886Z","dependency_job_id":"c4998031-fdb4-4e92-99a4-72b67f7debf5","html_url":"https://github.com/rgl/winps","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/rgl/winps","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rgl%2Fwinps","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rgl%2Fwinps/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rgl%2Fwinps/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rgl%2Fwinps/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rgl","download_url":"https://codeload.github.com/rgl/winps/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rgl%2Fwinps/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28692290,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-23T11:01:27.039Z","status":"ssl_error","status_checked_at":"2026-01-23T11:00:26.909Z","response_time":59,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: 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":["psrp","rdp","winrm","winrs"],"created_at":"2024-10-04T18:21:29.654Z","updated_at":"2026-01-23T12:54:12.488Z","avatar_url":"https://github.com/rgl.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# About\n\nRemote execute a command in a Windows machine using WinRM/WinRS/RDP.\n\nThis uses:\n\n* [pypsrp library](https://pypi.org/project/pypsrp/)\n* [xfreerdp application](https://www.freerdp.com/)\n* [scrot application](https://github.com/resurrecting-open-source-projects/scrot)\n* [xdotool application](https://github.com/jordansissel/xdotool)\n\n# Usage\n\nStart the [windows-domain-controller vagrant environment](https://github.com/rgl/windows-domain-controller-vagrant).\n\nInstall docker.\n\nBuild the `winps` container image:\n\n```bash\ndocker build -t winps .\n```\n\nSet the environment variables:\n\n```bash\nexport WINPS_HOST='dc.example.com'\nexport WINPS_HOST_IP='192.168.56.2'\nexport WINPS_USERNAME='EXAMPLE\\john.doe'\nexport WINPS_PASSWORD='HeyH0Password'\n```\n\nRemote execute the `whoami.exe` command:\n\n```bash\ndocker run --rm -i \\\n    --add-host \"$WINPS_HOST:$WINPS_HOST_IP\" \\\n    winps \\\n    winps \\\n    execute \\\n    --host \"$WINPS_HOST\" \\\n    --username \"$WINPS_USERNAME\" \\\n    --password \"$WINPS_PASSWORD\" \\\n    --script 'whoami.exe /all'\n```\n\nStart an headless RDP session:\n\n```bash\ndocker run --rm -i \\\n    --name winps \\\n    --add-host \"$WINPS_HOST:$WINPS_HOST_IP\" \\\n    --volume \"$PWD:/host:rw\" \\\n    --env WINPS_HOST \\\n    --env WINPS_USERNAME \\\n    --env WINPS_PASSWORD \\\n    winps \\\n    bash \u003c\u003c'EOF'\nset -euo pipefail\nxvfb-run \\\n    \"--server-args=-screen 0 1024x768x24\" \\\n    xfreerdp \\\n        /log-level:WARN \\\n        /cert:ignore \\\n        \"/v:$WINPS_HOST\" \\\n        \"/u:$WINPS_USERNAME\" \\\n        \"/p:$WINPS_PASSWORD\" \\\n        /f \\\n        /dynamic-resolution \\\n        +credentials-delegation\nEOF\n```\n\nOpen another shell.\n\nSet the environment variables as done initially.\n\nTake a screenshot:\n\n```bash\ndocker exec winps screenshot /host/screenshot.png\n```\n\nRun the calculator in the interactive desktop:\n\n```bash\ndocker run --rm -i \\\n    --add-host \"$WINPS_HOST:$WINPS_HOST_IP\" \\\n    --env WINPS_USERNAME \\\n    winps \\\n    winps \\\n    execute \\\n    --host \"$WINPS_HOST\" \\\n    --username \"$WINPS_USERNAME\" \\\n    --password \"$WINPS_PASSWORD\" \\\n    --env WINPS_USERNAME \\\n    --script - \u003c\u003c'EOF'\n$taskName = \"winps-$(New-Guid)\"\nRegister-ScheduledTask `\n    -TaskName $taskName `\n    -Principal (\n        New-ScheduledTaskPrincipal `\n            -UserId $env:WINPS_USERNAME `\n            -LogonType Interactive `\n            -RunLevel Highest\n    ) `\n    -Action (\n        New-ScheduledTaskAction `\n            -Execute win32calc.exe\n    ) `\n    | Out-Null\nStart-ScheduledTask `\n    -TaskName $taskName\nUnregister-ScheduledTask `\n    -TaskName $taskName `\n    -Confirm:$false\nEOF\n```\n\nTake a screenshot:\n\n```bash\ndocker exec winps screenshot /host/screenshot-calculator.png\n```\n\nSimulate the `Windows` (aka `Super`) keypress:\n\n```bash\ndocker exec winps keyboard key Super_L\n```\n\nTake a screenshot:\n\n```bash\ndocker exec winps screenshot /host/screenshot-keypress.png\n```\n\nLogoff all the RDP sessions:\n\n```bash\ndocker run --rm -i \\\n    --add-host \"$WINPS_HOST:$WINPS_HOST_IP\" \\\n    winps \\\n    winps \\\n    execute \\\n    --host \"$WINPS_HOST\" \\\n    --username \"$WINPS_USERNAME\" \\\n    --password \"$WINPS_PASSWORD\" \\\n    --env WINPS_USERNAME \\\n    --script - \u003c\u003c'EOF'\nquery.exe user | ForEach-Object {\n    # example query.exe user output:\n    #  USERNAME              SESSIONNAME        ID  STATE   IDLE TIME  LOGON TIME\n    #  john.doe              rdp-tcp#0           4  Active          9  9/24/2022 12:29 PM\n    if ($_ -match '^\\s*(?\u003cusername\u003e.+?)\\s+(?\u003csessionname\u003e.+?)\\s+(?\u003cid\u003e\\d+?)\\s+') {\n        New-Object PSObject -Property @{\n            Username = $Matches['username']\n            SessionName = $Matches['sessionname']\n            SessionId = $Matches['id']\n        }\n    }\n} `\n| Where-Object {\n    $_.SessionName -like 'rdp-*'\n} `\n| ForEach-Object {\n    Write-Host \"Logging off $($_.Username)...\"\n    logoff.exe $_.SessionId\n}\nEOF\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frgl%2Fwinps","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frgl%2Fwinps","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frgl%2Fwinps/lists"}