vnc

Execute commands on a remote host via VNC, using the vncdotool library. Connection settings are cached after the first command, so subsequent commands only need to specify what changes.

Warning

VNC sessions must be explicitly closed with cmd: close, otherwise AttackMate will hang on exit.

Note

Background mode is not supported for this commands.

vars:
  $SERVER_ADDRESS: 192.42.0.254
  $PORT: 5900
  $DISPLAY: 1
  $PASSWORD: password

commands:
  # Open a connection, take a screenshot, and create a named session:
  - type: vnc
    cmd: capture
    filename: screenshot.png
    hostname: $SERVER_ADDRESS
    port: $PORT
    display: $DISPLAY
    password: $PASSWORD
    creates_session: my_session

  # Type text using the existing session:
  - type: vnc
    cmd: type
    input: "echo hello world"
    session: my_session

  # Close the session and remove it from the session store:
  - type: vnc
    cmd: close
    session: my_session

cmd

The VNC action to perform. One of:

capture — take a screenshot and save it to filename
expectscreen — compare the current screen against filename; continue only if they match within maxrms
type — type a string on the remote host via input
key — press a key on the remote host via key
click — left-click at the current cursor position
rightclick — right-click at the current cursor position
move — move the cursor to (x, y)
close — close the session and remove it from the session store

Type:: str
Required:: True

Connection

hostname

Hostname or IP address of the remote VNC server.

Type:: str

port

Port to connect to on the remote host.

Type:: int
Default:: 5900
Required:: False

display

Display number to connect to on the remote host.

Type:: int
Default:: 1
Required:: False

password

Password for VNC authentication.

Type:: str

connection_timeout

Timeout in seconds for the initial connection to be established. Must be set in the first command that opens the connection.

Type:: int
Default:: 10
Required:: False

expect_timeout

Timeout in seconds for a command to complete. Passed to the VNC client when the connection is first established — must be set in the first command that opens the connection.

Type:: int
Default:: 60
Required:: False

Sessions

creates_session

Name to assign to the session opened by this command. Can be reused in subsequent commands via session. If omitted and no prior session exists, a session named default is created automatically.

Type:: str
Required:: False

session

Name of an existing VNC session to reuse. The session must have been created previously via creates_session.

Type:: str
Required:: False

Actions

filename

Path to save a screenshot (capture) or path to an image file to compare against the current screen (expectscreen).

Type:: str
Required:: when cmd: capture or cmd: expectscreen

maxrms

Maximum RMS (root mean square) error allowed when comparing screens with expectscreen. Lower values require a closer match.

Type:: float
Default:: 0
Required:: False

input

Text to type on the remote host. Used with the type command.

Type:: str
Required:: when cmd: type

key

Key to press on the remote host. Used with the key command.

Type:: str
Required:: when cmd: key

x

Horizontal cursor position for the move command.

Type:: int
Required:: when cmd: move

y

Vertical cursor position for the move command.

Type:: int
Required:: when cmd: move