@hawthorne/carioca NPM

Hawthorne's Carioca

Carioca is a node.js library used to enumerate SMB shares, files and directories on a given host.

This library, built around the smbclient will stream all identified information by automating the following workflow:

Remotely connect to the server and list any available SMB shares;
For any identified share, attempt to perform anonymous authentication;
Given an authenticated share, recursively list all the files and directories;
Identified file and directory entries will be streamed as events.

Carioca can be leverage as an effective smb enumeration tool, useful in collection of information related to public non-indexed files and folders.

Getting Started

These instructions will get you a copy of the project up and running on your local machine for development and testing purposes. Additional details about Carioca's programatic interface and tutorials can be found under the project documentation page.

Prerequisites

Carioca requires the binary version of smbclient (version 4.8.5 was tested during development) tool and while the tool is not bundled with the Carioca project a build.sh script is provided to automate source acquisition and the building process. The build script will be automatically called during the npm install process.

If your environment already provides access to a suitable smbclient binary, please see the Carioca#Options.CLIENT documentation.

Carioca expects to be run under nodejs v8.X or superior.

Installing

Use the npm install command as follows:

$ npm install --save @hawthorne/carioca

Alternatively you can clone the project source code and run the npm install command inside the project folder, as follows:

$ git clone https://github.com/hawthorne/carioca.git
$ cd carioca
$ npm install

Known build issues

After upgrading to OSX Mojave, the smbclient build may fail with an error message mentioning Undefined symbols for architecture x86_64. In this case, attempt the following: brew link readline --force.

Example usage

Carioca provides an event driven chainable API, the following example provides a general example of it's usage.

const Carioca = require('@hawthorne/carioca');
const carioca = new Carioca('172.16.1.30');


carioca.on('shares:error'   , (e, opts) => console.dir([e, opts]))
       .on('enumerate:error', (e, opts) => console.dir([e, opts]))
       .on('shares:entry'   , (entry)   => console.log(`Discovered share "${entry.canonical}"`))
       .on('enumerate:entry', (entry)   => console.log(`Found entry ${entry.canonical}`))
       .on('shares:end'     , ()        => console.log('Completed share listing operation'))
       .on('enumerate:end'  , ()        => console.log('Completed enumeration operations'))
       .enumerate({concurrency: 5});