Skip to content

Commit 4b3cf82

Browse files
committed
Adding scanner set up tutorial
Signed-off-by: Sebastian <sebastian.franz@iteratec.com>
1 parent 7382474 commit 4b3cf82

2 files changed

Lines changed: 326 additions & 0 deletions

File tree

Lines changed: 225 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,225 @@
1+
<!--
2+
SPDX-FileCopyrightText: 2021 iteratec GmbH
3+
4+
SPDX-License-Identifier: Apache-2.0
5+
-->
6+
7+
# Tutorial: Integrating PingCastle into the secureCodeBox
8+
9+
## Preface
10+
11+
PingCastle is an open-source tool to scan a company's active directory. It is able to identify potential security
12+
risks and anomalies, regarding password settings, account privileges and much more. However, as active directory
13+
has emerged as a tool from microsoft, PingCastle is also a tool that runs only on Windows.
14+
You can read more about our struggle to make it work on linux in this blog post(TODO).
15+
This tutorial is directed towards a solution that uses a virtual machine inside an ubuntu container to run
16+
PingCastle in this machine. Sounds like inception? It pretty much is, but it is the only solution known to date that
17+
enables us to run it on a linux container.
18+
19+
## General architecture of the solution
20+
21+
Docker <- Ubuntu <- VirtualBox <- Windows VM <- PingCastle
22+
23+
That means that we run PingCastle in our Windows VM that runs in a virtualbox inside an ubuntu container.
24+
25+
More specifically:
26+
* Ubuntu 18 with systemd enabled (FROM jrei/systemd-ubuntu)
27+
* Virtual Box (tested version: 6.1.16_Ubuntur140961, use latest version)
28+
* Windows 10 VM
29+
If you use it for non-commercial usages and want to test our solution, you can use a trial version (Expires in 90 days):
30+
[Windows 10 VM Trial](https://developer.microsoft.com/de-de/windows/downloads/virtual-machines/) (Choose VirtualBox image)
31+
* PingCastle 2.9.2.1 (latest)
32+
33+
## Step-By-Step Walkthrough
34+
35+
Now let's dive into the crazy inception and have our system run a linux docker with windows!
36+
All you need is a Linux base system (preferably Ubuntu, we did not test any other linux distro!) where **Virtual Box
37+
is installed.**
38+
39+
### 1. Setting up the Windows 10 VM
40+
In the first step we will set up our Windows VM. In order to do that you need to run it as a virtual machine in
41+
Virtual Box. If you have downloaded the trial version mentioned above, you simply have to import it in Virtual Box
42+
and start the VM.
43+
Our goal is to have a Windows VM that logs in automatically on start-up, is connected to the network where the active
44+
directory is running and is able to run a PingCastle scan.
45+
46+
<details>
47+
<summary> WindowsVM Setup </summary>
48+
0. Install your specific language & keyboard Settings (optional, but can be useful)
49+
50+
1. Allow login without password for VirtualBox:
51+
[Source Stackoverflow](https://stackoverflow.com/questions/35372516/vboxmanage-error-the-specified-user-was-not-able-to-logon-on-guest)
52+
53+
"Run" -> "gpedit.msc".
54+
Windows Settings -> Security Settings -> Local Policies -> Security Options -> Accounts:
55+
Limit local account use of blank passwords to console logon only -> set it to DISABLED.
56+
57+
2. Establish VPN Connection to the network where the AD is located (if not used in the network anyway)
58+
59+
If the container is always running in the company's network, this step should not be necessary.
60+
<details>
61+
<summary>Otherwise you have to automatically connect to the VPN on startup</summary>
62+
63+
Automatically connect to VPN on startup:
64+
- Create a file "autoConnectVPN.bat"
65+
- Add the following line to the file:
66+
c:\windows\system32\rasdial.exe "domain" [/domain:domain.de]
67+
- Go To: C:\Users\USER\AppData\Roaming\Microsoft\Windows\Start Menu\Programs\Startup
68+
- Create shortlink to the autoConnectVPN.bat file
69+
70+
**Unfortunately, we experienced that this does not always work with PingCastle. The connection was established,
71+
but PingCastle refused to find the network. We provide a very dirty workaround that is not by any means error-prove.
72+
It should only be used if all other possibilities failed, and you want to test if the docker container is working at all.**
73+
```
74+
Dirtiest workaround: Use python to automatically click on the connection symbol:
75+
1. Install python 3.x and pip, add python to path, then (python -m) pip install pywin32
76+
77+
2. Create a script that just clicks "manually" on the connection symbols. (Read the mouse coordinates and click them)
78+
```
79+
</details>
80+
81+
3. Hang VM into the domain:
82+
83+
3.1 Open Powershell.exe as Administrator(!)
84+
85+
3.2 Type in the following command: Add-Computer -DomainName domain.de -NewName PingCastleVM
86+
87+
3.3 Type in your credentials (Username is the domain shortcut, e.g. pschmidt; Password is your regular PW)
88+
89+
3.4 If you are succesfull, this message shows:
90+
WARNING: The changes will take effect after you restart the computer (your computer name).
91+
92+
3.5 Restart VM
93+
94+
3.6 Check date&time, maybe the timezone has to be set manually to have a correct system time
95+
96+
4. Download necessary tools:
97+
98+
4.1 [Download PingCastle](https://github.com/vletoux/pingcastle/releases/download/2.9.2.1/PingCastle_2.9.2.1.zip)
99+
100+
4.2 Unzip to path: *C:\PingCastle*
101+
102+
4.3 We found it most useful and the easiest way not to call PingCastle directly but via a script.
103+
So create healthcheck.cmd in *C:\PingCastle* :
104+
```
105+
cd C:\PingCastle
106+
PingCastle.exe --healthcheck --server domain.com
107+
```
108+
*cd* necessary because otherwise guestcontrol will use a wrong default path.
109+
110+
4.4 Check if you can successfully scan your domain via the script!
111+
112+
5. Install Guest Additions for Virtual Box
113+
114+
6. Set Auto-Login:
115+
[Source: Tech-Faq](https://www.tech-faq.net/windows-10-autologin-einrichten/)
116+
117+
Create file and execute:
118+
```
119+
Windows Registry Editor Version 5.00
120+
121+
[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Passwordless\Device]
122+
"DevicePasswordLessBuildVersion"=dword:00000000
123+
```
124+
125+
7. Disable recovery modes to avoid that the VM gets stuck upon startup. (This step is optional and can for certain
126+
be further improved)
127+
128+
7.1 Open cmd as administrator
129+
130+
7.2
131+
```
132+
reagentc /info
133+
reagentc /disable
134+
```
135+
136+
8. Now check if you can run your VM in headless mode and execute a scan:
137+
```
138+
vboxmanage startvm WinVM --type headless
139+
vboxmanage showvminfo WinVM | grep "State" # should be "Running"
140+
vboxmanage guestcontrol WinVM run --exe "c:\\PingCastle\\healthcheck.cmd" --username USER
141+
```
142+
143+
9. Finally, you must export the modified appliance using VirtualBox (.ova)
144+
</details>
145+
146+
### 2. Docker Set-Up for Ubuntu with WindowsVM
147+
Next, we will integrate our created WindowsVM into an Ubuntu docker container.
148+
We hereby use an already existing Ubuntu18 container that has *systemd* enabled,
149+
which is crucial for virtual box to function.
150+
151+
<details>
152+
<summary>Docker Setup</summary>
153+
154+
Dockerfile:
155+
```
156+
FROM jrei/systemd-ubuntu
157+
158+
# VirtualBox
159+
RUN apt-get update \
160+
&& apt-get -y install wget \
161+
&& apt-get -y install gnupg2 \
162+
&& apt-get -y install systemd \
163+
&& apt-get -y install python3 \
164+
&& apt-get -y install software-properties-common \
165+
&& apt-get -y install unzip \
166+
&& wget -q https://www.virtualbox.org/download/oracle_vbox_2016.asc -O- | apt-key add - \
167+
&& wget -q https://www.virtualbox.org/download/oracle_vbox.asc -O- | apt-key add - \
168+
&& add-apt-repository "deb https://download.virtualbox.org/virtualbox/debian bionic contrib" \
169+
&& apt-get -y update \
170+
&& apt-get -y install linux-headers-generic \
171+
&& mkdir WindowsVM \
172+
&& apt-get -y install virtualbox
173+
174+
175+
# Add run pingcastle script
176+
ADD run_pingcastle_healthcheck.py run_pingcastle_healthcheck.py
177+
```
178+
179+
Now we have to do some manual configurations, so we must run the container. In --device, you have to provide the
180+
path where vboxdrv on your base system is located.
181+
```
182+
docker run -d --privileged \
183+
--name windocvm --network=host \
184+
--device /dev/vboxdrv:/dev/vboxdrv \
185+
-v /sys/fs/cgroup:/sys/fs/cgroup:ro \
186+
-v /tmp:/tmp -it windocvm
187+
```
188+
189+
190+
Next, copy the WindowsVM to the created container:
191+
```
192+
docker cp WindowsVM/WinVM.ova windocvm:WindowsVM/WinVM.ova
193+
```
194+
195+
Change to the running container and import and start the VM:
196+
```
197+
docker exec -it windocvm /bin/bash
198+
199+
cd WindowsVM \
200+
&& vboxmanage import WinVM.ova \
201+
&& vboxmanage list vms \
202+
&& vboxmanage startvm WinVM --type headless \
203+
&& vboxmanage showvminfo WinVM | grep "State"
204+
```
205+
206+
After that you can push the docker image to your own docker repository or proceed with the local image.
207+
</details>
208+
209+
### 3. Create docker container to handle the scan
210+
From the now created docker container, we can create a new one that has all the attributes from the one above and is
211+
able to execute our scan with a python script. This container can finally be added to the cluster and perform the
212+
automated scans.
213+
214+
<details>
215+
<summary>Dockerfile</summary>
216+
217+
```
218+
FROM docker.yourrepo.com/windocvm:latest
219+
220+
CMD python3 run_pingcastle_healthcheck.py
221+
```
222+
</details>
223+
224+
225+
And that's it! You can now add your docker container to the securecodebox cluster and apply a scan.yaml.
Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
"""
2+
SPDX-FileCopyrightText: 2021 iteratec GmbH
3+
4+
SPDX-License-Identifier: Apache-2.0
5+
"""
6+
7+
"""
8+
This script starts a pingcastle healthcheck scan in the docker container, that has virtual box running a windows vm with
9+
pingcastle. If the VM is not running, it tries to start it. Otherwise, it will directly call the script in the VM to
10+
run the scan. In the end, it will transfer the created result file to the host container.
11+
"""
12+
13+
import os
14+
import time
15+
import pathlib
16+
import subprocess
17+
18+
# Check if Windows VM is already running
19+
20+
running_vm = subprocess.Popen("vboxmanage showvminfo WinVM | grep 'State'", shell=True, stdout=subprocess.PIPE)
21+
22+
state_output = str(running_vm.stdout.read())
23+
running_vm.stdout.close()
24+
25+
if "running" in state_output:
26+
print("Windows VM already running, skipping start.")
27+
else:
28+
# Start Windows VM
29+
print("Starting WindowsVM..!")
30+
start_vm = subprocess.Popen("vboxmanage startvm WinVM --type headless ", shell=True, stdout=subprocess.PIPE)
31+
start_vm.wait()
32+
start_output = str(start_vm.stdout.read())
33+
34+
if start_vm.returncode == 0 and "successfully started" in start_output:
35+
print("Windows VM successfully started!")
36+
print("Waiting for VM to be running..")
37+
while "running" not in state_output:
38+
time.sleep(1)
39+
running_vm = subprocess.Popen("vboxmanage showvminfo WinVM | grep 'State'", shell=True,
40+
stdout=subprocess.PIPE)
41+
state_output = str(running_vm.stdout.read())
42+
43+
print("Windows VM is running!")
44+
for i in range(90):
45+
print("Waiting until VM is all set up:", 90-i)
46+
time.sleep(1)
47+
48+
# Start PingCastle Scan:
49+
print("Waiting for scan to start..")
50+
time.sleep(5)
51+
52+
print("Running PingCastle Healthcheck for domain.com")
53+
pingcastle_scan = subprocess.Popen("vboxmanage guestcontrol WinVM run --exe "
54+
"'c:\\PingCastle\\healthcheck.cmd' --username USER",
55+
shell=True,
56+
stdout=subprocess.PIPE,
57+
bufsize=1)
58+
lines = []
59+
for line in iter(pingcastle_scan.stdout.readline, b''):
60+
print(line)
61+
lines.append(str(line))
62+
pingcastle_scan.stdout.close()
63+
pingcastle_scan.wait()
64+
65+
success_message = "Task Perform analysis for domain.com completed"
66+
if len(lines) == 0 or success_message not in lines[-1]:
67+
print("Something went wrong with the scan.. See lines:", lines)
68+
else:
69+
print("PingCastle Healthcheck successfully finished!")
70+
71+
print("Grapping generated .xml and .html files..")
72+
# Remove all files if scan directory already exists:
73+
if os.path.isdir("PingCastleReports/"):
74+
for file in os.listdir("PingCastleReports/"):
75+
os.remove("PingCastleReports/" + file)
76+
else:
77+
os.mkdir("PingCastleReports/")
78+
79+
vbox_xml_transfer = subprocess.Popen("vboxmanage guestcontrol WinVM copyfrom --target-directory PingCastleReports/ "
80+
"'C:\\PingCastle\\ad_hc_domain.com.xml' --username USER",
81+
shell=True,
82+
stdout=subprocess.PIPE)
83+
vbox_xml_transfer.wait()
84+
85+
vbox_html_transfer = subprocess.Popen(
86+
"vboxmanage guestcontrol WinVM copyfrom --target-directory PingCastleReports/ "
87+
"'C:\\PingCastle\\ad_hc_domain.com.html' --username USER",
88+
shell=True,
89+
stdout=subprocess.PIPE)
90+
vbox_html_transfer.wait()
91+
92+
if vbox_html_transfer.returncode == 0 and vbox_xml_transfer.returncode == 0:
93+
# Verify that files have been transferred:
94+
for file in os.listdir("PingCastleReports"):
95+
fname = pathlib.Path("PingCastleReports/" + file)
96+
assert fname.exists(), f'No such file: {fname}' # check that the file exists
97+
98+
print("All scan files have been successfully transferred, quitting now.")
99+
else:
100+
print("Files have not been successfully transferred.. Exit codes: (xml), (html)",
101+
vbox_xml_transfer.returncode, vbox_html_transfer.returncode)

0 commit comments

Comments
 (0)