RETINA API DOCUMENTATION

General

This document explains the general Retina API. Information contained in this document is subject to change without notice.

Retina Architecture

The Retina architecture is an example of an extensible audit platform. Retina is designed to allow for pluggable components that can extend its functionality. There are two main parts of Retina. The first half is called the shell. The shell handles all user interface aspects of a scan, such as reporting, displaying results, alerting, and scan range entry. The second half of Retina is contained within scanner.exe, and is the actual scanning engine for Retina. The two halves communicate via a well defined communication mechanism. This mechanism is one way, allowing the scanning engine to report its findings to the shell, but not query information directly from the shell.

The Scanning Process

The Retina scanning process is multithreaded, and has been designed to be multithread safe. This allows Retina to implement multiple threads handling different hosts at the same time. Because of this, a slow host will not necessarily slow down the entire scan.

The process of scanning a host occurs in roughly the following manner:

ICMP ping: This step establishes if the host is responding.

Target setup: The specific details of the target are built, such as MAC addresses, reverse DNS hostnames and other details.

Syn Scan: Using a series of TCP syn packets, Retina scans the host to determine which ports are responding.

Protocol Detection: Whenever a port is found to be open, it is sent to the protocol detection stage. This offers a banner and protocol that is detected for a specific open port.

OS Detection: Using a series of packets designed to 'fingerprint' the target operating system, Retina matches the output against a database of known operating systems.

Audit Phase: The audit phase is effectively the second half of the scan and encompasses the basic 'vulnerability' scan portion of the audit.

The host, port, protocol, and OS detection phases are beyond the scope of Retina's open API, and so we will focus on the audit phase, since this allows one to write custom auditing code to audit specific services and protocols.

The Audit Phase

As Retina enters the audit phase, it knows basic information about the target host, such as OS (if detected), open ports, and the protocols running on those ports. This allows Retina to deal with each open port in a specific way, giving it a chance to do audits based on port number or protocol detected.

The process of auditing happens like this per host:

for (each open port)

run registered always audits.

Extending Retina

There are two ways to add audits to Retina. The first and simpler method is to add new vulnerability audits to existing Retina modules. The second is to write completely new scanning modules.

Adding new audits to existing modules is achieved by writing custom vulnerability checks (RTHs). RTHs offer a quick and easy way to extend the current code to check for new vulnerabilities or other policies. Writing a new RTH requires no coding knowledge and doesnt require you to enter a compiler or write a line of code.

Each module within Retina offers a range of abilities (usually relating to the protocol it is named after, or some aspect of it). However, advanced users may find it necessary to write new modules to expand Retinas capabilities. Modules can be written in virtually any windows programming language (as long as it can use DLL imported functions), and may be written as either standalone programs, or as DLLs. The majority of Retina modules are currently written as DLL's to improve speed and communication ability.

RTH Wizard

Creating a Retina RTH is done using the Audits Wizard. To launch the wizard, select Audits Wizard from the Retina Tools menu.

The above dialog will appear, prompting you to enter necessary information to create your audit. The following is a description of the fields used by the Audit Wizard:

• Check Name: Enter the name of the actual vulnerability. You can name the vulnerability check anything you want. For example 'Remote IIS4.0 buffer overflow in .htr'.
• Category: The category the audit will be displayed in from within the Retina Policies interface.
• Risk (Unlabeled): Choose a risk level for your audit. This information is displayed to the user, and is used when sending alerts. Valid choices are Information, Low, Medium and High.
• Vulnerability Description: This is where you can give a description of the vulnerability for Retina to display within its interface. Usually the description is where you tell a user about the extent of the vulnerability found.
• Vulnerability Fix: This field is used in order to give users general information on how to fix the vulnerability.
• Check Type: This page gathers the specific information for your audit. Select the type of check, and then fill in the corresponding audit information for that check type.

• Optional URL 1: A URL to a website (usually containing additional fix information, etc).
• Optional URL Description 1: A description for Optional URL 1. Usually the name of the website or a document title.
• Optional URL 2: A URL to a website (usually containing additional fix information, etc).
• Optional URL Description 2: A description for Optional URL 2. Usually the name of the website or a document title
• Optional URL 3: A URL to a website (usually containing additional fix information, etc).
• Optional URL Description 3: A description for Optional URL 3. Usually the name of the website or a document title
• CVE-ID: If the vulnerability you are checking for has a CVE number, enter it here. For more information on CVE, visit https://cve.mitre.org/cve.
• Bugtraq ID: If the vulnerability you are check for has a Bugtraq ID, enter it here. For more information of Bugtraq, visit https://securityfocus.com.
• Vulnerabile Operating Systems: Specifies which operating systems are to be scanned by this audit.

Once you have completed the wizard, click Finish. You will now be able to select your new audit by selecting Policies from the Retina Tools menu.

Writing Custom Modules using the Retina Open API

The Retina API is a class of wrappers that ease the use of writing custom audit code in the Retina environment. Most of the functionality is in the areas of selecting audits to run and writing the results back to the shell. This portion will explain how to write modules using the standard Retina API.

To include the Retina API in a project:

• Add the retsimple.h file to an include directory
• Add the retsimple.lib to your linking libraries

The included example is written in C. The instructions are written for Microsoft Visual C++ 6. If you are using a different compiler or programming language, the steps will be different.

1. Create a new Win32 DLL project, Chose an empty DLL project;
2. After the project is created, add a new file to the project named ProjectName.c
3. After the file is created, edit the settings for the project. Add retsimple.lib to the linker section and make certain retsimple.h is in one of your allowed Include directories.

The code:

#define WIN32_LEAN_AND_MEAN

#include <winsock2.h>

#include <stdio.h>

#include <windows.h>

#include 'retsimple.h'

#define CODEBASE 'AuditSample'

int WriteTest(char *ip);

__declspec( dllexport) int AuditSample(pAARGS aargs);

int AuditSample(pAARGS aargs)

__except(Ret_Except(GetExceptionCode(),GetExceptionInformation(),TRUE,'AuditSample'))

return(0);

//Grab's the service's banner and stores

//it to a global buffer

int WriteTest(char *ip)

See Appendix A for a Full detailed description of each function exported in the Retina API.

Installing A New Module

To install a new module, select Plugins Wizard from the Retina Tools menu.

• From the Plugin Module dialog, click New. The New Module wizard will appear.

• Module Name: The path to your module EXE or DLL file. Use the browse button to locate the file.
• Description: A brief description of what the module does.
• Protocol: The protocol that your module scans.
• Ports: A list of ports that your module scans.
• Audit Local: Choose Yes if you want your module to run when a local scan is performed (even if the selected protocol or port is not found).
• Always Audit: Choose Yes if you want your module to always run even if the corresponding port was not found to be open.

Click Finish to add your module to the list. Click Exit to close the Plugins Wizard.

Appendix A - Retina API Reference

Shell Write Functions

void Ret_Status(char *IPAddress, char *Status);

Adds generic information to an already existing entry

void Ret_Add_Generic_Info(char *IPAddress, char *Section, char *Specific, char *Title, char *Subtext);

Adds generic information to an already existing entry

void Ret_Add_Generic_Section(char *IPAddress, char *Path, char *Title, char *Description);

Adds a generic entry to an already existing section

void Ret_Add_User(char *IPAddress, char *UserName, char *Description);

Adds a user with a description to the users section

void Ret_Add_User_Info(char *IPAddress, char *UserName, char *Title, char *Subtext);

Adds info to an already existing user in the users section

void Ret_Add_Share(char *IPAddress, char *Share, char *Description);

Adds a share with a description to the shares section

void Ret_Add_Share_Info(char *IPAddress, char *Share, char *Title, char *Subtext);

Adds info to an already existing share in the shares section

void Ret_Add_Service(char *IPAddress, char *Service, char *Description);

Adds a service with a description to the Services section

void Ret_Add_Service_Info(char *IPAddress, char *Service, char *Title, char *Subtext);

Adds info to an already existing share in the shares section

void Ret_Add_Port(char *IPAddress, int Port, char *Description);

Adds a port with a description to the ports section

void Ret_Add_Port_Info(char *IPAddress, int Port, char *Title, char *Subtext);

Adds info to an already existing port in the Ports section

void Ret_Add_Machine(char *IPAddress, char *Machine, char *Description);

Adds an entry with a description to the machine section

void Ret_Add_Machine_Info(char *IPAddress, char *Machine, char *Title, char *Subtext);

Adds info to an already existing entry in the Machine section

void Ret_Add_Audit(char *IPAddress, char *RTH, char *Codebase);

Adds an audit to the audits section. It is based off of an RTH filename

void Ret_Add_General(char *IPAddress, char *General, char *Description);

Adds an entry with a description to the general section

void Ret_Add_General_Info(char *IPAddress, char *General, char *Title, char *Subtext);

Adds info to an already existing entry in the general section

Memory Functions

void * Ret_Malloc(size_t size);

Allocates a block of memory from the process heap, it also has exception handlers to catch and handle any errors that may occur.

void Ret_Free(void *memblock);

Frees a block of memory from the process heap, it also has exception handlers to catch and handle any errors that may occur.

Debug Functions

void Ret_DebugOut ( const char *out);

Prints an entry to the RETDEBUG.log file if logging is enabled.

void Ret_Fatal (char *reason); 

Produces a message box with a fatal error that stops the scan.

Appendix B - Glossary

Shell: The outer, visible part of Retina. It is responsible for logging data to a database, displaying results, and handling alerts, among other functions.

Scanner.exe: The Retina scanning engine. It handles all of the audits and reports back to the shell its findings.

RTH: A collection of information that define audits in the Retina scan

Modules: EXE, DLL, or other type of code that contains custom auditing code. May work with RTHs to offer a specific amount of configurability and extensibility.