Learn about our RFC process, Open RFC meetings & more.Join in the discussion! »


0.0.6 • Public • Published

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:

  1. Remotely connect to the server and list any available SMB shares;
  2. For any identified share, attempt to perform anonymous authentication;
  3. Given an authenticated share, recursively list all the files and directories;
  4. 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.


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.


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('');
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});

Project details


Please read the CODE_OF_CONDUCT.md document for details on our code of conduct.


Carioca uses SemVer for versioning. For the versions available, see available tags on this repository.



This project is licensed under the MIT License - see the LICENSE file for details.


npm i @hawthorne/carioca

DownloadsWeekly Downloads






Unpacked Size

37.1 kB

Total Files


Last publish


  • avatar