Metadata-Version: 2.1
Name: oab
Version: 1.0.0
Summary: Offline Address Books decoder
Home-page: https://github.com/HubTou/oab/
Author: Hubert Tournier
Author-email: hubert.tournier@gmail.com
License: BSD 3-Clause License
Project-URL: Bug Tracker, https://github.com/HubTou/oab/issues
Keywords: HubTools
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: BSD License
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: openpyxl
Requires-Dist: pnu-libpnu
Requires-Dist: prettytable
Requires-Dist: rich

# OAB(1)

## NAME
oab - Microsoft Exchange/Outlook Offline Address Book (.oab files) decoder

## INSTALLATION
Once you have installed [Python](https://www.python.org/downloads/) v3.10+ and its packages manager [pip](https://pip.pypa.io/en/stable/installation/),
use the following command to install this tool:

```
pip install oab
```

## SYNOPSIS
**oab**
\[--bar|-b\]
\[--output|-o FILE\]
\[--csv|-C\]
\[--delimiter|-d CHAR\]
\[--excel|-E\]
\[--json|-J\]
\[--compact|-c\]
\[--ident|-i INT\]
\[--table|-T\]
\[--width|-w INT\]
\[--debug\]
\[--help|-?\]
\[--version\]
\[--\]
filename

## DESCRIPTION
The **oab** utility and library decode Microsoft Exchange/Outlook Offline Address Book (.oab) files,
and provide their contents as a Python dictionary or in CSV (delimiter separated values), Excel, JSON, text or tabular formats.

### Utility
By default, the utility will print the resulting Python dictionary to standard output as pretty printed text.

It is possible to get CSV, Excel, JSON and pretty table formats instead by using the *--csv|-C*, *--excel|-E*, *--json|-J* or *--table|-T* options.

For all these formats, the *--output|-o* option can be used to redirect output to file(s) with an argument indicating the desired basename.
**oab** will add the appropriate file extension and, in the case of CSV and pretty table formats, will separate the results in *users* and *lists* contents.

The delimiter used for CSV files can be changed from a comma to the argument of the *--delimiter|-d* option.

The style used for JSON files can be changed to compact mode with the *--compact|-c* option,
or with an indentation different from 4 spaces with the argument of the *--indent|-i* option.

The terminal width used for the pretty table files can be changed from the default 80 columns to the argument of the *--width|-w* option.
You should especially use this option When redirecting the program output to a file...

Last and least, you can disable the progress bar with the *--bar|-b* option.

### Python library
There are 5 public functions, one for loading an oab file,
the others for converting its result into another format:

```Python
import oab

# data is a dict
# filename is a str. For example, "udetails.oab"
# progress_bar is a bool
data = oab.load_oab_file(filename, progress_bar=False)

# delimiter is a str, normally for a single character
# users and lists will be list instances
users, lists = oab.oab2csv(data, parameters["delimiter"])

# basename is a str. For example, "address_book"
oab.oab2excel(data, basename)

# compact is a bool
# indent is an int
json_data = oab.oab2json(data, compact=False, indent=2)

# width is an int
users, lists = oab2table(data, width=173)
```

### OPTIONS
Options | Use
------- | ---
--bar\|-b|Toggle OFF progress bar
--output\|-o FILE|Output result into FILE (extension added by oab)
--csv\|-C|Format results as CSV
--delimiter\|-d CHAR|Use CHAR as delimiter for CSV format
--excel\|-E|Format results as Excel tabbed file
--json\|-J|Format results as JSON
--compact\|-c|Use compact JSON format
--ident\|-i INT|Use INT spaces for indented JSON format
--table\|-T|Format results as tables
--width\|-w INT|Use INT columns in table format
--debug|Enable debug mode
--help\|-?|Print usage and a short help message and exit
--version|Print version and exit
--|Options processing terminator

## ENVIRONMENT
The COLUMNS environment variable will be used in tabular format if present.

## EXIT STATUS
The **oab** utility exits 0 on success, and >0 if an error occurs.

## EXAMPLES
To generate pretty tables with relevant information about users and mailing lists in 2 files, use the following command:
```Shell
$ oab --table --width 170 --output addressbook udetails.oab
```

## SEE ALSO
### Specifications
* [Offline address books in Exchange Online](https://learn.microsoft.com/en-us/exchange/address-books/offline-address-books/offline-address-books)
* [Offline Address Book (OAB) File Format and Schema](https://learn.microsoft.com/en-us/openspecs/exchange_server_protocols/ms-oxoab/b4750386-66ec-4e69-abb6-208dd131c7de)
* [Offline Address Book (OAB) Public Folder Retrieval Protocol](https://learn.microsoft.com/en-us/openspecs/exchange_server_protocols/ms-oxpfoab/258a07a7-34a7-4373-87c1-cddf51447d00)

### Other implementations
* SysTools [OAB Viewer](https://www.systoolsgroup.com/oab/viewer/)
* Mauville [OABtoCSV](https://github.com/Mauville/OABtoCSV)
* byteDJINN [BOA](https://github.com/byteDJINN/BOA)
* antimatter15 [boa](https://github.com/antimatter15/boa)

## STANDARDS
The **oab** utility is not a standard UNIX command.

This implementation tries to follow the [PEP 8](https://www.python.org/dev/peps/pep-0008/) style guide for [Python](https://www.python.org/) code.

## PORTABILITY
To be tested under Windows.

## HISTORY
This program was made on a rainy sunday in order to investigate the contents of my Outlook .oab files.

It was then used to help cleaning my company's global address list.

## LICENSE
It is available under the [3-clause BSD license](https://opensource.org/licenses/BSD-3-Clause).

## AUTHORS
[Hubert Tournier](https://github.com/HubTou)

This program is inspired by antimatter15's [boa](https://github.com/antimatter15/boa) and includes snippets of code from:
* [Mark@StackOverflow](https://stackoverflow.com/users/2606953/mark)
* [Wolph@StackOverflow](https://stackoverflow.com/users/54017/wolph)

## CAVEAT
Only uncompressed version 4 full details files are supported at this time.

## BUGS
Excel reports an error while opening generated XLSX files,
but after accepting its recovery offer these files appear to be fine...

## SECURITY CONSIDERATIONS
OAB files and the results generated by this program contain sensitive personal information
that should not be left unprotected.

There are known attacks in the wild targetting these files:
* [Attacking MS Exchange Web Interfaces](https://swarm.ptsecurity.com/attacking-ms-exchange-web-interfaces/)
* [Critical Microsoft Exchange Flaw: What is CVE-2021-26855?](https://www.upguard.com/blog/cve-2021-26855)
* grnbeltwarrior [OAB_Cleaver](https://github.com/grnbeltwarrior/OAB_Cleaver)

