Skip to content

API

A full list of supported functions and properties available in GreyScript is contained below.

Global Variables

params

A list object of command line parameters provided when called from the terminal

Usage Example

Running mycommand --help:

["--help"]

mycommand:

[]

mycommand try out this 1:

["try", "out", "this", "1"]

if params.len == 0 or params[0] == "--help" then
    print("usage information about my command")
else
...
As shown above, params originates from the full parameter string provided in the terminal, separated into an array of strings separated by each space (" ").

System Functions

In addition to string, number, list and map functions, there are a small number of native system functions.

globals & locals

See scope

print(data)

Takes data (optional any) and prints it to the terminal.

If no data is supplied, prints an empty line to the terminal.

Usage Example

print(123)
print("123")
print(range(1, 5))
print({"a":"b"})
print(1==1)
123
123
[1, 2, 3, 4, 5]
{"a":"b"}
1

wait(duration)

Pauses the script for the indicated duration (number). If duration is not specified, the default value is 1 second.

time

Returns the number of seconds since the program execution began.

Usage Example

print("Begin")
wait(0.2)
print(time)
Begin
0.201

typeof(var)

Takes a variable (any)

Returns the type of variable (string). Supported types:

Usage Example

v = 32
w = "thirty two"
x = [3, 2]
y = {32: "thirty two"}
z = function()
      //do something
      return 1
    end function

typeof(v)
typeof(w)
typeof(x)
typeof(y)
typeof(z)
typeof(@z)
number
string
list
map
number
function

Per example z, note that where a variable is a function, and that function returns any data then typeof(var) will return the type of data, because providing the function to typeof actually invokes the function.

It may therefore be advisable to reference a variable when using typeof, as in last line above.

md5(str)

Returns the md5 hash (string) of the provided string.

Usage Example

X = 55
print(md5("orange"))
print(md5(str(X)))
fe01d67a002dfa0f3ac084298142eccd
b53b3a3d6ab90ce0268229151c9bde11

get_router(IP)

Takes an IP address (string) - lan or public. If no IP is provided, defaults to the user's router

Returns a Router object or null if not found

get_shell(user, password)

Returns a Shell object for the shell executing the script

Takes an optional username and password to return a shell for that user

Usage Example

myshell = get_shell
print("Type: " + typeof(myshell))

file = myshell.host_computer.File("/etc/passwd")
print(file.name)
Type: shell
passwd

nslookup(domain)

Takes a domain name (string)

Returns string - either the public IP of the provided domain or Not found

whois(IP)

Takes a public IP address (string)

Returns a string containing several lines of whois information or No Info available

is_valid_ip(string)

Evaluates whether a string is a valid IPv4 address

Takes a string and returns 0 (false) or 1 (true)

Usage Example

tof = function(v)
  return ("in" * (v == 0)) + "valid"
end function

print(tof(is_valid_ip("abc")))
print(tof(is_valid_ip("192.168.0.1")))
print(tof(is_valid_ip("192.168.0.99")))
print(tof(is_valid_ip("192.168.0.999")))
invalid
valid
valid
invalid

The third IP above evaluates as true because it conforms to a valid IPv4 format, even if that IP doesn't exist in Grey Hack. The fourth IP fails because it is out of range (0.0.0.0 to 0.255.255.255).

is_lan_ip(string)

Evaluates whether a string is a valid LAN IPv4 address (ranging from 192.168.0.0 to 192.168.255.255).

Takes a string and returns 0 (false) or 1 (true)

command_info(ref)

Obtain usage information for a native Grey Hack command

Takes a usage string and returns the usage information (string) or "Unknown info"

Usage Example

print(command_info("ftp_usage"))
Usage: ftp [[email protected]] [ip address]
Example: ftp [email protected] 127.0.0.1

current_date

Returns a string with the current date and time on the player's clock

Date/Time Format

In Grey Hack, a date and time strings are in the format d-m-yyyy hh:mm (e.g. 29-4-2017 19:04)

current_path

Returns the path (string) to the working directory of the terminal (e.g. /home/bert)

parent_path

Takes a file or directory path (string)

Returns the path to the parent directory (string)

Usage Example

print(parent_path("/etc/passwd"))
print(parent_path(current_path))
print(parent_path("/"))
/etc
/home/user
/

Note the returned path does not have a trailing slash.

home_dir

Returns the path (string) to the active user's home directory (e.g. /home/username)

program_path

Returns the absolute path (string) to the executing script (e.g. /bin/myprogram)

active_user

Returns the username of the active user (string)

user_mail_address

Returns the email address (string) of the active user, or null if they do not have an email address

user_bank_number

Returns the bank account number (int) of the active user, or null if they do not have a bank account

format_columns(str)

Returns string data formatted into columns (such as for use in the nmap command)

Rows should be separated by a new line, while columns are separated by a space. See the below example.

Usage Example

data = "COL1 COL2 COL3" //define our column titles
data = data + "\none two three" //define our data, each column data separated by a space
data = data + "\nthing1 thing2 thing3" //add another row
print(format_columns(data))
COL 1    COL2    COL3
one      two     three
thing1   thing2  thing3

user_input(msg, isPassword)

Requests the user's input, along with an optional message and password mask (int 0 or 1), and returns the input to a variable

If isPassword is provided and is 1 then the user's input will be masked in the terminal (e.g. ******* instead of machina)

Usage Example

name = user_input("What is your name?")
print("Hello " + name + "!")
The script will pause and the user will be prompted to enter their name, after which the script will resume and the user input (string) will be returned as the declared variable (in this case name).

include_lib(libpath)

Includes an external library on the executing machine, specified by its file path (string). Libraries contain their own methods, and operate as custom objects.

Returns a Metaxploit object that corresponds to the provided library, or null on failure

Usage Example
cryptools = include_lib("/lib/crypto.so") //providing /lib/crypto.so exists, returns the crypto object
if not cryptools then exit("Error: Missing crypto library") //error handling
print(cryptools.decipher("/etc/passwd")) //prints the deciphered root password

bitwise(operator, num1, num2)

Manipulate data at the bit level. Bitwise operates on one or more bit patterns or binary numerals at the level of their individual bits.

The operator argument accepts the following operators:

  • & (Bitwise AND)
  • | (Bitwise OR)
  • ^ (Bitwise XOR)
  • << (Left Shift)
  • >> (Right Shift)
  • >>> (Unsigned Right Shift)
Usage Example

result = bitwise("&", 12, 25)
print("Result: " + result)
Result: 8

clear_screen

Clears all text from the terminal that is running the script.

This clears ALL output from the terminal, not just output printed from the current script.

exit(msg=null)

Exits the script, optionally printing a provided message (string). The script will abort and no further lines of code will be processed

Usage Example

print("Hello")

exit("Script Exited")

print("Goodbye")
Hello
Script Exited

for i in range(1, 10)
  print(i)
  if i == 5 then exit
end for
print("Something else")
1
2
3
4
5

Objects

There are nine objects in the GreyScript API, which contain their own properties and functions:

Router

Instantiated by get_router, this object provides the following functions:

public_ip

Returns the public IP address (string) of the router

local_ip

Returns the LAN IP address (string) of the router

device_ports(IP)

Takes a LAN IP address (string)

Returns a list of Port objects for ports used on the corresponding machine

computers_lan_ip

Returns a list of IP addresses for machines connected to the router

ping_port(port)

Takes an external port number (int)

Returns the Port object for the specified port if forwarding is configured for it; otherwise returns null

port_info(Port)

Takes a Port object

Returns service information for that port (string)

used_ports

Returns a list of Port objects - all ports configured for forwarding on the router

bssid_name

Returns the mac address (bssid string) of the router

essid_name

Returns the name (essid string) of the router

Computer

Computer is instantiated by Shell.host_computer and provides the following functions:

change_password(user, password)

Changes an existing user's password. Takes a user (string) and password (string).

Returns 1 on success, or error string on failure

Root Only

This function can only be executed when the script is executed by the root user.

create_user(user, password)

Creates a new user on the computer. Requires a username (string) and password (string).

Returns 1 on success, or error string on failure

Root Only

This function can only be executed when the script is executed by the root user.

create_group(username, groupname)

Creates a group (named with a chosen string) for the named user (string username of an existing user account)

Returns 1 (true) on success or error string on failure

Root Only

This function can only be executed when the script is executed by the root user.

create_folder(path, name)

Creates a directory name within path

Returns 1 (true) on success or 0 (false) / null on failure

Usage Example
comp = get_shell.host_computer
comp.create_folder(current_path, "foldername")

close_program(pid)

Terminates a process. Takes a process ID (int).

Returns 1 on success, 0 if the process cannot be found, or an error string on failure to terminate the process

connect_wifi(interface, bssid, essid, password)

Connects to a wireless network. Takes an interface (string e.g. eth0), bssid (string), essid (string), and password (string)

Returns 1 on successful connection, null if the network cannot be found, or an error string on connection failure

delete_user(user, removeHome)

Deletes a user, and optionally deletes their /home/user directory. Requires username (string) and takes an optional removeHome int (1 or 0)

Returns 1 on success, or error string on failure

Root Only

This function can only be executed when the script is executed by the root user.

delete_group(username, groupname)

Deletes a group (named string) on the machine, removing it from the named user (string username of an existing user)

Returns 1 (true) on success or error string on failure

Root Only

This function can only be executed when the script is executed by the root user.

Group Deletion is Per User

Deleting a group for a user removes that group from that specific user. This function will not remove any identically titled group from any other user.

groups(username)

Returns a line delimited string of all groups a given user (string username) belongs to

network_devices

Returns a string with a list of network device(s) on the computer

Usage Example

print(get_shell.host_computer.network_devices)
eth0 85978LM False

The above output shows the network interface (eth0), chipset (85978LM) and whether monitoring is enabled (False).

get_ports

Returns a list of Port objects for services running on the computer

is_network_active

Does the Computer have internet access?

Returns 1 (true) or 0 (false)

lan_ip

Returns the LAN IP (string) of the computer

show_procs

Returns a string listing the processes currently running on the machine

Usage Example

print("Current user: " + active_user + "\n\nCurrent processes:")
print(get_shell.host_computer.show_procs)
Current user: bert

Current processes:
USER PID CPU MEM COMMAND
root 9230 0.0% 13.7% kernel_task
root 8709 0.0% 11.2% Xorg
bert 7365 0.0% 14.1% Browser.exe
bert 7399 0.0% 8.6% Terminal.exe

touch(path, filename)

Creates an empty file with the name of filename (string) in the chosen directory path (string)

Returns 1 on success, or a string (containing an error) on failure

Usage Example
comp = get_shell.host_computer
comp.touch("/path/to/directory", "filename")
print(comp.File("/path/to/directory/filename").name) // "filename"

wifi_networks(interface)

Takes a network interface (string e.g. eth0)

Returns a list object of WiFi networks available to the user's machine.

Usage Example

networks = get_shell.host_computer.wifi_networks("eth0")
for net in networks
  print(net.split(" ")[0])
end for
C7:E7:C8:43:9A:E7
3F:65:29:C5:83:AB
FE:50:51:7F:61:47
72:5B:80:A7:77:48
65:61:E4:79:B3:D0
5B:14:B4:D3:B5:BD

Each item in the list contains (space delimited) bssid, signal strength, and essid.

File(path)

Obtain a File object for a file on the machine.

Returns a File object or null if the file does not exist

Usage Example
comp = get_shell.host_computer
myfile = comp.File("/path/to/file")
myfile.delete

comp.File("/path/to/directory").delete

Relative path

File() does not require an absolute path.

comp = get_shell.host_computer
bank = comp.File("Config/Bank.txt")
print(bank.content)

If a user runs this from their default terminal (where the working directory will be /home/user), then it will print the contents of their Bank.txt file.

If the user opens terminal but changes directory before running the above script, the relative path won't return a File object and this script will result in errors. Accordingly, you would need to check the file exists or the content is not null before trying to print the file.

File

File is typically instantiated by Computer.File and provides the following functions:

Directories

In this documentation, file refers to both files and folders. Folders and files are of course separate, but a file object can represent a directory.

So remember: folders may not be files but a folder is a file. See is_folder below.

copy(path, newname)

Copies a file to a new directory path (string) with the provided name (string). Overwrites any existing file with newname.

On success, returns 1 and the terminal outputs the copied file dialogue. On failure, returns either an error (string) such as permission denied or null (if File object not valid).

Usage Example

comp = get_shell.host_computer
comp.File("/etc/passwd").copy(current_path, "passfile")
This example copies the /etc/passwd file to the working directory and names it 'passfile'.

move(path, newname)

Moves a file to the specified path, similar to File.copy, except that the original file is moved.

On success, returns 1. On failure, returns either an error (string) such as permission denied or null (if File object not valid).

Usage Example

get_shell.host_computer.File("/home/user/Downloads").move("/home/user/Desktop", "Downloads")
This example moves the user's Downloads folder to their Desktop.

rename(newname)

Renames a file to newname (string)

Returns a string (empty on success, or with an error on failure)

Usage Example

fruit = get_shell.host_computer.File("apple")
if(typeof(fruit) == "file") then
  fruit.rename("banana")
end if
This example looks in the current directory for a file named 'apple' and if it exists, renames it 'banana'.

chmod(perms, recursive)

Modifies the file's permissions

Takes a permissions string (e.g. u+wr) and optional recursive flag (int 0 or 1)

If the file is a folder and the recursive flag is 1, the permissions change will apply recursively, to all the files and folders inside the target folder.

Returns a string (empty on success, or with an error on failure)

Usage Example
comp = get_shell.host_computer
pwd = comp.File("/etc/passwd")
etc = comp.File("/etc")

pwd.chmod("o-wrx") //removes read, write, and execute permissions for guest on the file
etc.chmod("o-wrx", 1) //removes rwx permissions for guest on /etc and all files within /etc

set_content(content)

Sets a file's contents to content (string)

Returns 1 on success, or a string (containing an error) on failure

Usage Example
myfile = get_shell.host_computer.File("/etc/passwd")
myfile.set_content("blah") // sets the content of /etc/passwd to "blah"

set_group(group, recursive)

Modifies the file's ownership group

Takes the name of a group (string) and optional recursive flag (int 0 or 1)

If the file is a folder and the recursive flag is 1, the ownership change will apply recursively, to all the files and folders inside the target folder.

Root Only

This function can only be executed when the script is executed by the root user.

group

Returns the group (string) to whom the file belongs

path

Returns the full path (string) to the file or directory.

Usage Example
computer = get_shell.host_computer
file = computer.File("/root/Config/Bank.txt")

print(file.path) // /root/Config/Bank.txt
print(file.parent.path) // /root/Config

content

Returns the contents of the file (string)

is_binary

Is the file a binary file?

Returns 1 (true) or 0 (false)

Only for files. Returns null if called on a directory

is_folder

Is the file a directory?

Returns 1 (true) or 0 (false)

has_permission(p)

Does the active user have permission to read, write, or execute the file?

Takes a permission (string: r, w, or x) and returns 1 (true) or 0 (false)

set_owner(owner, recursive)

Modifies the file's ownership user

Takes the name of a user (string) and optional recursive flag (int 0 or 1)

If the file is a folder and the recursive flag is 1, the ownership change will apply recursively, to all the files and folders inside the target folder.

Root Only

This function can only be executed when the script is executed by the root user.

owner

Returns the username of the file's owner (string)

permissions

Returns a string with the permissions set on the file (e.g. -rw-rw-r--)

To set permissions, see chmod

parent

Returns the File object of the file's parent directory (or null if the initial object is /)

Usage Example

comp = get_shell.host_computer
print(comp.File("/Public/htdocs/downloads").parent.name)
htdocs

name

Returns the name of the file (string)

size

Returns the size (int) of the file in bytes

delete

Deletes the file and returns a string (empty on success, or with an error on failure)

get_folders

Returns a list of File objects for all folders in the target directory

Only for directories. Returns null if called on a file

get_files

Returns a list of File objects for all files (excluding folder) in the target directory

Only for directories. Returns null if called on a file

Port

Port objects be obtained by Router.ping_port, Router.used_ports, Router.computer_ports or Computer.get_ports, and provide for the following functions:

get_lan_ip

Returns the LAN IP Address for which the port forwarding record is configured (string)

is_closed

Is the port closed?

Returns 1 (true) or 0 (false)

port_number

Returns the port number (int)

Shell

Shell objects can be instantiated by get_shell and provide the following functions:

host_computer

Returns the shell's Computer object

Usage Example
mycomputer = get_shell.host_computer

print(mycomputer.File("/etc/passwd").content)
// prints the contents of /etc/passwd on the user machine

start_terminal

Launches an active terminal. The colour of the terminal will change and show the IP of the connected shell.

Usage Example
shell = get_shell.connect_service("88.137.62.95", 21, "root", "kuroshitsuji", "ftp")
if shell then shell.start_terminal

Intended to be executed on a remote shell

connect_service(IP, port, user, pass, service)

Connects to a remote service (i.e. ssh/ftp) to obtain a remote shell. Requires an IP address (string), port (int), username (string), password (string), and takes an optional service (string)

Returns a Shell object or null on failure

Tip

The service parameter defaults to ssh, and need not be defined where connecting to ssh. But when specified, this parameter should be either ftp or ssh.

Usage Example
mypc = get_shell
remote = mypc.connect_service("39.62.143.12", 22, "root", "We<3nigma")

if remote then
  print(remote.host_computer.File("/etc/passwd").content)
  //prints the contents of /etc/passwd on this remote machine
end if

Info

On failure, the terminal may also output a connection error (e.g. can't connect: incorrect user/password). This comes from the server and passes around the script, direct to the client terminal.

scp(file, folder, shell)

Upload or download files to/from the local shell to/from a remote shell

Takes the path (string) to a file on the shell machine, path to a folder (string) on the remote shell machine, and the shell (Shell) of the machine to copy the file to

Returns 1 on success, or a string (containing an error) on failure

Usage Example
myPC = get_shell
remote = myPC.connect_service("31.19.44.137", 22, "root", "AceofSpades")

myPC.scp("/var/system.log", "/root", remote)
// uploads system.log from the user machine to the root directory on the remote machine

remote.scp("/var/system.log", home_dir, myPC)
// downloads system.log from the remote server to the user directory on the user machine

launch(program, params)

Executes a program (string path to program) with optional parameters (string)

Returns null on success, or 0 on failure

Usage Example
get_shell.launch("/bin/cat", "/etc/passwd")

Limitations

The launch() function only works with script-based terminal commands.

build(srcpath, buildpath)

Compiles an executable binary from a source file

Requires a path to a source file (string) and a directory path (string) to where the binary will be saved. The binary will be created with the same name as the source file, without a file extension.

Returns a string (empty on success, or with an error on failure)

Usage Example

get_shell.build("/home/user/myprogram.src", "/home/user")
The above would create an executable named 'myprogram' in the folder '/home/user'.

Requires absolute paths

You must provide absolute paths (i.e. /full/path/to/file) for both srcpath and buildpath.

masterkey(IP, port, user)

Takes an IP (string), port (int), and optional user (string) defaulting to root

Obtains a shell on a machine, regardless of exploits, permissions or closed ports. Returns a shell object, or null on failure

Usage Example
host = get_shell
remote = host.masterkey("83.137.19.41", 80)
// opens a remote shell as root on the specified IP and port

Mods Only

This function is only available to in-game moderators, when moderator tools are enabled. If you are not eligible to use this function, it will return null.

FtpShell

FtpShell objects can be instantiated by shell.connect_service when connecting to ftp, and provide the following functions:

start_terminal

put

Alias of shell.scp

host_computer

masterkey

Alias of shell.masterkey

Crypto

The Crypto object comes from the Crypto library in /lib/crypto.so and is instantiated by include_lib.

aircrack(filepath)

Cracks a router's WiFi password. Requires the path to a pcap file created by the aireplay command

Returns the target router's WiFi password (string) or null on failure (the terminal will also output an error)

aireplay(bssid, essid, maxAcks)

Capture packets from a wireless interface. Requires bssid (string) and essid (string), and an optional maxAcks (number).

If maxAcks is not provided, use Ctrl+C to stop the capturing and save data to a file file.cap in the current directory.

If maxAcks is provided, the command will stop automatically once the number of ACKs received exceeds maxAcks, saving the file.cap as described above.

Returns null, or a string containing an error message

airmon(option, interface)

Enables/Disables WiFi monitoring. Requires an option (string: either "start" or "stop") and network interface (e.g. "eth0")

Usage Example
crypto = include_lib("/lib/crypto.so")
crypto.airmon("start", "eth0")

decipher(user, encryptedPass)

Attempts to decipher an encrypted password.

Takes a username (string) and encrypted password (hash string). Returns either the deciphered password (string), or null on failure

smtp_user_list(IP, port)

Connects to a mail service and returns a list object of all users on the machine, along with their email address on the server (or otherwise an email not found string)

Takes an IP address and port (int)

Usage Example

crypto = include_lib("/lib/crypto.so")
mail = crypto.smtp_user_list("88.231.19.24", 25)
print(mail)
["root email not found", "Toche exists [email protected]", "Krireng exists [email protected]"]

MetaLib

The MetaLib object represents all libraries in Grey Hack. It can be instantiated by Metaxploit.load.

overflow(memoryAddress, value, extra)

Performs a buffer overflow attack on the library at the specified memory address (string) with the specified vulnerable value

Additional data may need to be provided (via the optional extra parameter) for the exploit to work (e.g. if the exploit changes a user's password)

Usage Example

meta = include_lib("/lib/metaxploit.so")
lib = meta.load("/lib/kernel_module.so")
flow = lib.overflow("0x2CF07FF0", "bl_treel")
print("Returned: " + typeof(flow))
[email protected]:/home/guest#  myprogram
Starting attack...success!
Privileges obtained from user: Fstevio
Returned: shell
[email protected]/home/Fstevio#  
In the above scenario, we would have already utilised Metaxploit.scan to find a vulnerable memory address, followed by Metaxploit.scan_address to reveal the vulnerable value.

lib_name

Returns the file name of the library (string)

version

Returns the version number (string) of the library

Usage Example
meta = include_lib("/lib/metaxploit.so")
if not meta then exit("Error: missing /lib/metaxploit.so")
lib = meta.load("/lib/init.so")
if not lib then exit("Error: missing /lib/init.so")
print(lib.version) // 1.0.0

Metaxploit

The metaxploit object comes from metaxploit.so which can be found in the hackshop. After downloading it and moving it to the /lib folder, it can be instantiated with include_lib.

load(library)

Loads a library (string path) in memory and returns a MetaLib object

Returns either the MetaLib object, or null on failure

net_use(IP, port)

Connects to an IP address and establishes a NetSession, which grants remote access to the target's libraries; either the service library running on the optional port (int), or the router libraries if no port has been specified.

Returns a NetSession object, or null on failure

rshell_client(IP, port, procName)

Takes an optional port (number) and process name (string).

Launches a process on the victim's machine, which silently tries to continuously connect in the background to the specified address and port.

Setup

For the reverse shell to run successfully, the rshell service must be installed and the portforward configured correctly on the machine where the server is waiting for the victim's connection.

rshell_server

Returns a list of shell objects that have been reverse shell connected to this machine.

Setup

In order to manage the connections received, the rshell service must be installed on the machine that receives the victims' connections.

scan(MetaLib)

Scans a MetaLib for vulnerable memory addresses and returns them in a list

Returns either the memory addresses (list), or null on failure

scan_address(metalib, memoryAddress)

Scans a specific memory address and returns information about all its vulnerabilities

Returns either the information about the memory vulnerabilities (string), or null on failure

sniffer(saveEncSource)

Takes an optional argument to save the source (boolean)

The terminal listens to the network packets of any connection that passes through this device. When any connection information is captured, it prints a string with the obtained data. It can save the source code of the encode script if saveEncSource is true.

Returns null if the listener could not be started.

NetSession

This object is instantiated by Metaxploit.net_use.

dump_lib

Returns the MetaLib object of the library behind the service to which the NetSession belongs

Usage Example

meta = include_lib("/lib/metaxploit.so")
net = meta.net_use("88.231.19.24", 22)
libssh = net.dump_lib
print(libssh.lib_name + " v" + libssh.version)
libssh.so v1.0.4